diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..3c3629e --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +node_modules diff --git a/.npmignore b/.npmignore new file mode 100644 index 0000000..e216ae5 --- /dev/null +++ b/.npmignore @@ -0,0 +1,2 @@ +/node_modules +/test diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 0000000..05f32a1 --- /dev/null +++ b/.travis.yml @@ -0,0 +1,19 @@ +language: node_js +node_js: + - "4.0" + - "iojs" + - "0.12" + - "0.11" + - "0.10" + - "0.8" + - "0.6" + +sudo: false + +before_install: + npm install -g npm@'>=1.4.3' + +matrix: + allow_failures: + - node_js: "0.8" + - node_js: "0.6" diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..3f9d40b --- /dev/null +++ b/LICENSE @@ -0,0 +1,20 @@ +Copyright (c) 2013 Ben Newman + +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..7b63289 --- /dev/null +++ b/README.md @@ -0,0 +1,488 @@ +AST Types +=== + +This module provides an efficient, modular, +[Esprima](https://github.com/ariya/esprima)-compatible implementation of +the [abstract syntax +tree](http://en.wikipedia.org/wiki/Abstract_syntax_tree) type hierarchy +pioneered by the [Mozilla Parser +API](https://developer.mozilla.org/en-US/docs/SpiderMonkey/Parser_API). + +[![Build Status](https://travis-ci.org/benjamn/ast-types.png?branch=master)](https://travis-ci.org/benjamn/ast-types) + +Installation +--- + +From NPM: + + npm install ast-types + +From GitHub: + + cd path/to/node_modules + git clone git://github.com/benjamn/ast-types.git + cd ast-types + npm install . + +Basic Usage +--- +```js +var assert = require("assert"); +var n = require("ast-types").namedTypes; +var b = require("ast-types").builders; + +var fooId = b.identifier("foo"); +var ifFoo = b.ifStatement(fooId, b.blockStatement([ + b.expressionStatement(b.callExpression(fooId, [])) +])); + +assert.ok(n.IfStatement.check(ifFoo)); +assert.ok(n.Statement.check(ifFoo)); +assert.ok(n.Node.check(ifFoo)); + +assert.ok(n.BlockStatement.check(ifFoo.consequent)); +assert.strictEqual( + ifFoo.consequent.body[0].expression.arguments.length, + 0); + +assert.strictEqual(ifFoo.test, fooId); +assert.ok(n.Expression.check(ifFoo.test)); +assert.ok(n.Identifier.check(ifFoo.test)); +assert.ok(!n.Statement.check(ifFoo.test)); +``` + +AST Traversal +--- + +Because it understands the AST type system so thoroughly, this library +is able to provide excellent node iteration and traversal mechanisms. + +If you want complete control over the traversal, and all you need is a way +of enumerating the known fields of your AST nodes and getting their +values, you may be interested in the primitives `getFieldNames` and +`getFieldValue`: +```js +var types = require("ast-types"); +var partialFunExpr = { type: "FunctionExpression" }; + +// Even though partialFunExpr doesn't actually contain all the fields that +// are expected for a FunctionExpression, types.getFieldNames knows: +console.log(types.getFieldNames(partialFunExpr)); +// [ 'type', 'id', 'params', 'body', 'generator', 'expression', +// 'defaults', 'rest', 'async' ] + +// For fields that have default values, types.getFieldValue will return +// the default if the field is not actually defined. +console.log(types.getFieldValue(partialFunExpr, "generator")); +// false +``` + +Two more low-level helper functions, `eachField` and `someField`, are +defined in terms of `getFieldNames` and `getFieldValue`: +```js +// Iterate over all defined fields of an object, including those missing +// or undefined, passing each field name and effective value (as returned +// by getFieldValue) to the callback. If the object has no corresponding +// Def, the callback will never be called. +exports.eachField = function(object, callback, context) { + getFieldNames(object).forEach(function(name) { + callback.call(this, name, getFieldValue(object, name)); + }, context); +}; + +// Similar to eachField, except that iteration stops as soon as the +// callback returns a truthy value. Like Array.prototype.some, the final +// result is either true or false to indicates whether the callback +// returned true for any element or not. +exports.someField = function(object, callback, context) { + return getFieldNames(object).some(function(name) { + return callback.call(this, name, getFieldValue(object, name)); + }, context); +}; +``` + +So here's how you might make a copy of an AST node: +```js +var copy = {}; +require("ast-types").eachField(node, function(name, value) { + // Note that undefined fields will be visited too, according to + // the rules associated with node.type, and default field values + // will be substituted if appropriate. + copy[name] = value; +}) +``` + +But that's not all! You can also easily visit entire syntax trees using +the powerful `types.visit` abstraction. + +Here's a trivial example of how you might assert that `arguments.callee` +is never used in `ast`: +```js +var assert = require("assert"); +var types = require("ast-types"); +var n = types.namedTypes; + +types.visit(ast, { + // This method will be called for any node with .type "MemberExpression": + visitMemberExpression: function(path) { + // Visitor methods receive a single argument, a NodePath object + // wrapping the node of interest. + var node = path.node; + + if (n.Identifier.check(node.object) && + node.object.name === "arguments" && + n.Identifier.check(node.property)) { + assert.notStrictEqual(node.property.name, "callee"); + } + + // It's your responsibility to call this.traverse with some + // NodePath object (usually the one passed into the visitor + // method) before the visitor method returns, or return false to + // indicate that the traversal need not continue any further down + // this subtree. + this.traverse(path); + } +}); +``` + +Here's a slightly more involved example of transforming `...rest` +parameters into browser-runnable ES5 JavaScript: + +```js +var b = types.builders; + +// Reuse the same AST structure for Array.prototype.slice.call. +var sliceExpr = b.memberExpression( + b.memberExpression( + b.memberExpression( + b.identifier("Array"), + b.identifier("prototype"), + false + ), + b.identifier("slice"), + false + ), + b.identifier("call"), + false +); + +types.visit(ast, { + // This method will be called for any node whose type is a subtype of + // Function (e.g., FunctionDeclaration, FunctionExpression, and + // ArrowFunctionExpression). Note that types.visit precomputes a + // lookup table from every known type to the appropriate visitor + // method to call for nodes of that type, so the dispatch takes + // constant time. + visitFunction: function(path) { + // Visitor methods receive a single argument, a NodePath object + // wrapping the node of interest. + var node = path.node; + + // It's your responsibility to call this.traverse with some + // NodePath object (usually the one passed into the visitor + // method) before the visitor method returns, or return false to + // indicate that the traversal need not continue any further down + // this subtree. An assertion will fail if you forget, which is + // awesome, because it means you will never again make the + // disastrous mistake of forgetting to traverse a subtree. Also + // cool: because you can call this method at any point in the + // visitor method, it's up to you whether your traversal is + // pre-order, post-order, or both! + this.traverse(path); + + // This traversal is only concerned with Function nodes that have + // rest parameters. + if (!node.rest) { + return; + } + + // For the purposes of this example, we won't worry about functions + // with Expression bodies. + n.BlockStatement.assert(node.body); + + // Use types.builders to build a variable declaration of the form + // + // var rest = Array.prototype.slice.call(arguments, n); + // + // where `rest` is the name of the rest parameter, and `n` is a + // numeric literal specifying the number of named parameters the + // function takes. + var restVarDecl = b.variableDeclaration("var", [ + b.variableDeclarator( + node.rest, + b.callExpression(sliceExpr, [ + b.identifier("arguments"), + b.literal(node.params.length) + ]) + ) + ]); + + // Similar to doing node.body.body.unshift(restVarDecl), except + // that the other NodePath objects wrapping body statements will + // have their indexes updated to accommodate the new statement. + path.get("body", "body").unshift(restVarDecl); + + // Nullify node.rest now that we have simulated the behavior of + // the rest parameter using ordinary JavaScript. + path.get("rest").replace(null); + + // There's nothing wrong with doing node.rest = null, but I wanted + // to point out that the above statement has the same effect. + assert.strictEqual(node.rest, null); + } +}); +``` + +Here's how you might use `types.visit` to implement a function that +determines if a given function node refers to `this`: + +```js +function usesThis(funcNode) { + n.Function.assert(funcNode); + var result = false; + + types.visit(funcNode, { + visitThisExpression: function(path) { + result = true; + + // The quickest way to terminate the traversal is to call + // this.abort(), which throws a special exception (instanceof + // this.AbortRequest) that will be caught in the top-level + // types.visit method, so you don't have to worry about + // catching the exception yourself. + this.abort(); + }, + + visitFunction: function(path) { + // ThisExpression nodes in nested scopes don't count as `this` + // references for the original function node, so we can safely + // avoid traversing this subtree. + return false; + }, + + visitCallExpression: function(path) { + var node = path.node; + + // If the function contains CallExpression nodes involving + // super, those expressions will implicitly depend on the + // value of `this`, even though they do not explicitly contain + // any ThisExpression nodes. + if (this.isSuperCallExpression(node)) { + result = true; + this.abort(); // Throws AbortRequest exception. + } + + this.traverse(path); + }, + + // Yes, you can define arbitrary helper methods. + isSuperCallExpression: function(callExpr) { + n.CallExpression.assert(callExpr); + return this.isSuperIdentifier(callExpr.callee) + || this.isSuperMemberExpression(callExpr.callee); + }, + + // And even helper helper methods! + isSuperIdentifier: function(node) { + return n.Identifier.check(node.callee) + && node.callee.name === "super"; + }, + + isSuperMemberExpression: function(node) { + return n.MemberExpression.check(node.callee) + && n.Identifier.check(node.callee.object) + && node.callee.object.name === "super"; + } + }); + + return result; +} +``` + +As you might guess, when an `AbortRequest` is thrown from a subtree, the +exception will propagate from the corresponding calls to `this.traverse` +in the ancestor visitor methods. If you decide you want to cancel the +request, simply catch the exception and call its `.cancel()` method. The +rest of the subtree beneath the `try`-`catch` block will be abandoned, but +the remaining siblings of the ancestor node will still be visited. + +NodePath +--- + +The `NodePath` object passed to visitor methods is a wrapper around an AST +node, and it serves to provide access to the chain of ancestor objects +(all the way back to the root of the AST) and scope information. + +In general, `path.node` refers to the wrapped node, `path.parent.node` +refers to the nearest `Node` ancestor, `path.parent.parent.node` to the +grandparent, and so on. + +Note that `path.node` may not be a direct property value of +`path.parent.node`; for instance, it might be the case that `path.node` is +an element of an array that is a direct child of the parent node: +```js +path.node === path.parent.node.elements[3] +``` +in which case you should know that `path.parentPath` provides +finer-grained access to the complete path of objects (not just the `Node` +ones) from the root of the AST: +```js +// In reality, path.parent is the grandparent of path: +path.parentPath.parentPath === path.parent + +// The path.parentPath object wraps the elements array (note that we use +// .value because the elements array is not a Node): +path.parentPath.value === path.parent.node.elements + +// The path.node object is the fourth element in that array: +path.parentPath.value[3] === path.node + +// Unlike path.node and path.value, which are synonyms because path.node +// is a Node object, path.parentPath.node is distinct from +// path.parentPath.value, because the elements array is not a +// Node. Instead, path.parentPath.node refers to the closest ancestor +// Node, which happens to be the same as path.parent.node: +path.parentPath.node === path.parent.node + +// The path is named for its index in the elements array: +path.name === 3 + +// Likewise, path.parentPath is named for the property by which +// path.parent.node refers to it: +path.parentPath.name === "elements" + +// Putting it all together, we can follow the chain of object references +// from path.parent.node all the way to path.node by accessing each +// property by name: +path.parent.node[path.parentPath.name][path.name] === path.node +``` + +These `NodePath` objects are created during the traversal without +modifying the AST nodes themselves, so it's not a problem if the same node +appears more than once in the AST (like `Array.prototype.slice.call` in +the example above), because it will be visited with a distict `NodePath` +each time it appears. + +Child `NodePath` objects are created lazily, by calling the `.get` method +of a parent `NodePath` object: +```js +// If a NodePath object for the elements array has never been created +// before, it will be created here and cached in the future: +path.get("elements").get(3).value === path.value.elements[3] + +// Alternatively, you can pass multiple property names to .get instead of +// chaining multiple .get calls: +path.get("elements", 0).value === path.value.elements[0] +``` + +`NodePath` objects support a number of useful methods: +```js +// Replace one node with another node: +var fifth = path.get("elements", 4); +fifth.replace(newNode); + +// Now do some stuff that might rearrange the list, and this replacement +// remains safe: +fifth.replace(newerNode); + +// Replace the third element in an array with two new nodes: +path.get("elements", 2).replace( + b.identifier("foo"), + b.thisExpression() +); + +// Remove a node and its parent if it would leave a redundant AST node: +//e.g. var t = 1, y =2; removing the `t` and `y` declarators results in `var undefined`. +path.prune(); //returns the closest parent `NodePath`. + +// Remove a node from a list of nodes: +path.get("elements", 3).replace(); + +// Add three new nodes to the beginning of a list of nodes: +path.get("elements").unshift(a, b, c); + +// Remove and return the first node in a list of nodes: +path.get("elements").shift(); + +// Push two new nodes onto the end of a list of nodes: +path.get("elements").push(d, e); + +// Remove and return the last node in a list of nodes: +path.get("elements").pop(); + +// Insert a new node before/after the seventh node in a list of nodes: +var seventh = path.get("elements", 6); +seventh.insertBefore(newNode); +seventh.insertAfter(newNode); + +// Insert a new element at index 5 in a list of nodes: +path.get("elements").insertAt(5, newNode); +``` + +Scope +--- + +The object exposed as `path.scope` during AST traversals provides +information about variable and function declarations in the scope that +contains `path.node`. See [scope.js](lib/scope.js) for its public +interface, which currently includes `.isGlobal`, `.getGlobalScope()`, +`.depth`, `.declares(name)`, `.lookup(name)`, and `.getBindings()`. + +Custom AST Node Types +--- + +The `ast-types` module was designed to be extended. To that end, it +provides a readable, declarative syntax for specifying new AST node types, +based primarily upon the `require("ast-types").Type.def` function: +```js +var types = require("ast-types"); +var def = types.Type.def; +var string = types.builtInTypes.string; +var b = types.builders; + +// Suppose you need a named File type to wrap your Programs. +def("File") + .bases("Node") + .build("name", "program") + .field("name", string) + .field("program", def("Program")); + +// Prevent further modifications to the File type (and any other +// types newly introduced by def(...)). +types.finalize(); + +// The b.file builder function is now available. It expects two +// arguments, as named by .build("name", "program") above. +var main = b.file("main.js", b.program([ + // Pointless program contents included for extra color. + b.functionDeclaration(b.identifier("succ"), [ + b.identifier("x") + ], b.blockStatement([ + b.returnStatement( + b.binaryExpression( + "+", b.identifier("x"), b.literal(1) + ) + ) + ])) +])); + +assert.strictEqual(main.name, "main.js"); +assert.strictEqual(main.program.body[0].params[0].name, "x"); +// etc. + +// If you pass the wrong type of arguments, or fail to pass enough +// arguments, an AssertionError will be thrown. + +b.file(b.blockStatement([])); +// ==> AssertionError: {"body":[],"type":"BlockStatement","loc":null} does not match type string + +b.file("lib/types.js", b.thisExpression()); +// ==> AssertionError: {"type":"ThisExpression","loc":null} does not match type Program +``` +The `def` syntax is used to define all the default AST node types found in +[core.js](def/core.js), +[es6.js](def/es6.js), +[mozilla.js](def/mozilla.js), +[e4x.js](def/e4x.js), and +[fb-harmony.js](def/fb-harmony.js), so you have +no shortage of examples to learn from. diff --git a/def/babel.js b/def/babel.js new file mode 100644 index 0000000..608ffbc --- /dev/null +++ b/def/babel.js @@ -0,0 +1,105 @@ +require("./es7"); + +var types = require("../lib/types"); +var defaults = require("../lib/shared").defaults; +var def = types.Type.def; +var or = types.Type.or; + +def("Noop") + .bases("Node") + .build(); + +def("DoExpression") + .bases("Expression") + .build("body") + .field("body", [def("Statement")]); + +def("Super") + .bases("Expression") + .build(); + +def("BindExpression") + .bases("Expression") + .build("object", "callee") + .field("object", or(def("Expression"), null)) + .field("callee", def("Expression")); + +def("Decorator") + .bases("Node") + .build("expression") + .field("expression", def("Expression")); + +def("Property") + .field("decorators", + or([def("Decorator")], null), + defaults["null"]); + +def("MethodDefinition") + .field("decorators", + or([def("Decorator")], null), + defaults["null"]); + +def("MetaProperty") + .bases("Expression") + .build("meta", "property") + .field("meta", def("Identifier")) + .field("property", def("Identifier")); + +def("ParenthesizedExpression") + .bases("Expression") + .build("expression") + .field("expression", def("Expression")); + +def("ImportSpecifier") + .bases("ModuleSpecifier") + .build("imported", "local") + .field("imported", def("Identifier")); + +def("ImportDefaultSpecifier") + .bases("ModuleSpecifier") + .build("local"); + +def("ImportNamespaceSpecifier") + .bases("ModuleSpecifier") + .build("local"); + +def("ExportDefaultDeclaration") + .bases("Declaration") + .build("declaration") + .field("declaration", or(def("Declaration"), def("Expression"))); + +def("ExportNamedDeclaration") + .bases("Declaration") + .build("declaration", "specifiers", "source") + .field("declaration", or(def("Declaration"), null)) + .field("specifiers", [def("ExportSpecifier")], defaults.emptyArray) + .field("source", or(def("Literal"), null), defaults["null"]); + +def("ExportSpecifier") + .bases("ModuleSpecifier") + .build("local", "exported") + .field("exported", def("Identifier")); + +def("ExportNamespaceSpecifier") + .bases("Specifier") + .build("exported") + .field("exported", def("Identifier")); + +def("ExportDefaultSpecifier") + .bases("Specifier") + .build("exported") + .field("exported", def("Identifier")); + +def("ExportAllDeclaration") + .bases("Declaration") + .build("exported", "source") + .field("exported", or(def("Identifier"), null)) + .field("source", def("Literal")); + +def("CommentBlock") + .bases("Comment") + .build("value", /*optional:*/ "leading", "trailing"); + +def("CommentLine") + .bases("Comment") + .build("value", /*optional:*/ "leading", "trailing"); diff --git a/def/core.js b/def/core.js new file mode 100644 index 0000000..6441cdc --- /dev/null +++ b/def/core.js @@ -0,0 +1,359 @@ +var types = require("../lib/types"); +var Type = types.Type; +var def = Type.def; +var or = Type.or; +var shared = require("../lib/shared"); +var defaults = shared.defaults; +var geq = shared.geq; + +// Abstract supertype of all syntactic entities that are allowed to have a +// .loc field. +def("Printable") + .field("loc", or( + def("SourceLocation"), + null + ), defaults["null"], true); + +def("Node") + .bases("Printable") + .field("type", String) + .field("comments", or( + [def("Comment")], + null + ), defaults["null"], true); + +def("SourceLocation") + .build("start", "end", "source") + .field("start", def("Position")) + .field("end", def("Position")) + .field("source", or(String, null), defaults["null"]); + +def("Position") + .build("line", "column") + .field("line", geq(1)) + .field("column", geq(0)); + +def("File") + .bases("Node") + .build("program") + .field("program", def("Program")); + +def("Program") + .bases("Node") + .build("body") + .field("body", [def("Statement")]); + +def("Function") + .bases("Node") + .field("id", or(def("Identifier"), null), defaults["null"]) + .field("params", [def("Pattern")]) + .field("body", def("BlockStatement")); + +def("Statement").bases("Node"); + +// The empty .build() here means that an EmptyStatement can be constructed +// (i.e. it's not abstract) but that it needs no arguments. +def("EmptyStatement").bases("Statement").build(); + +def("BlockStatement") + .bases("Statement") + .build("body") + .field("body", [def("Statement")]); + +// TODO Figure out how to silently coerce Expressions to +// ExpressionStatements where a Statement was expected. +def("ExpressionStatement") + .bases("Statement") + .build("expression") + .field("expression", def("Expression")); + +def("IfStatement") + .bases("Statement") + .build("test", "consequent", "alternate") + .field("test", def("Expression")) + .field("consequent", def("Statement")) + .field("alternate", or(def("Statement"), null), defaults["null"]); + +def("LabeledStatement") + .bases("Statement") + .build("label", "body") + .field("label", def("Identifier")) + .field("body", def("Statement")); + +def("BreakStatement") + .bases("Statement") + .build("label") + .field("label", or(def("Identifier"), null), defaults["null"]); + +def("ContinueStatement") + .bases("Statement") + .build("label") + .field("label", or(def("Identifier"), null), defaults["null"]); + +def("WithStatement") + .bases("Statement") + .build("object", "body") + .field("object", def("Expression")) + .field("body", def("Statement")); + +def("SwitchStatement") + .bases("Statement") + .build("discriminant", "cases", "lexical") + .field("discriminant", def("Expression")) + .field("cases", [def("SwitchCase")]) + .field("lexical", Boolean, defaults["false"]); + +def("ReturnStatement") + .bases("Statement") + .build("argument") + .field("argument", or(def("Expression"), null)); + +def("ThrowStatement") + .bases("Statement") + .build("argument") + .field("argument", def("Expression")); + +def("TryStatement") + .bases("Statement") + .build("block", "handler", "finalizer") + .field("block", def("BlockStatement")) + .field("handler", or(def("CatchClause"), null), function() { + return this.handlers && this.handlers[0] || null; + }) + .field("handlers", [def("CatchClause")], function() { + return this.handler ? [this.handler] : []; + }, true) // Indicates this field is hidden from eachField iteration. + .field("guardedHandlers", [def("CatchClause")], defaults.emptyArray) + .field("finalizer", or(def("BlockStatement"), null), defaults["null"]); + +def("CatchClause") + .bases("Node") + .build("param", "guard", "body") + .field("param", def("Pattern")) + .field("guard", or(def("Expression"), null), defaults["null"]) + .field("body", def("BlockStatement")); + +def("WhileStatement") + .bases("Statement") + .build("test", "body") + .field("test", def("Expression")) + .field("body", def("Statement")); + +def("DoWhileStatement") + .bases("Statement") + .build("body", "test") + .field("body", def("Statement")) + .field("test", def("Expression")); + +def("ForStatement") + .bases("Statement") + .build("init", "test", "update", "body") + .field("init", or( + def("VariableDeclaration"), + def("Expression"), + null)) + .field("test", or(def("Expression"), null)) + .field("update", or(def("Expression"), null)) + .field("body", def("Statement")); + +def("ForInStatement") + .bases("Statement") + .build("left", "right", "body") + .field("left", or( + def("VariableDeclaration"), + def("Expression"))) + .field("right", def("Expression")) + .field("body", def("Statement")); + +def("DebuggerStatement").bases("Statement").build(); + +def("Declaration").bases("Statement"); + +def("FunctionDeclaration") + .bases("Function", "Declaration") + .build("id", "params", "body") + .field("id", def("Identifier")); + +def("FunctionExpression") + .bases("Function", "Expression") + .build("id", "params", "body"); + +def("VariableDeclaration") + .bases("Declaration") + .build("kind", "declarations") + .field("kind", or("var", "let", "const")) + .field("declarations", [def("VariableDeclarator")]); + +def("VariableDeclarator") + .bases("Node") + .build("id", "init") + .field("id", def("Pattern")) + .field("init", or(def("Expression"), null)); + +// TODO Are all Expressions really Patterns? +def("Expression").bases("Node", "Pattern"); + +def("ThisExpression").bases("Expression").build(); + +def("ArrayExpression") + .bases("Expression") + .build("elements") + .field("elements", [or(def("Expression"), null)]); + +def("ObjectExpression") + .bases("Expression") + .build("properties") + .field("properties", [def("Property")]); + +// TODO Not in the Mozilla Parser API, but used by Esprima. +def("Property") + .bases("Node") // Want to be able to visit Property Nodes. + .build("kind", "key", "value") + .field("kind", or("init", "get", "set")) + .field("key", or(def("Literal"), def("Identifier"))) + .field("value", def("Expression")); + +def("SequenceExpression") + .bases("Expression") + .build("expressions") + .field("expressions", [def("Expression")]); + +var UnaryOperator = or( + "-", "+", "!", "~", + "typeof", "void", "delete"); + +def("UnaryExpression") + .bases("Expression") + .build("operator", "argument", "prefix") + .field("operator", UnaryOperator) + .field("argument", def("Expression")) + // Esprima doesn't bother with this field, presumably because it's + // always true for unary operators. + .field("prefix", Boolean, defaults["true"]); + +var BinaryOperator = or( + "==", "!=", "===", "!==", + "<", "<=", ">", ">=", + "<<", ">>", ">>>", + "+", "-", "*", "/", "%", + "&", // TODO Missing from the Parser API. + "|", "^", "in", + "instanceof", ".."); + +def("BinaryExpression") + .bases("Expression") + .build("operator", "left", "right") + .field("operator", BinaryOperator) + .field("left", def("Expression")) + .field("right", def("Expression")); + +var AssignmentOperator = or( + "=", "+=", "-=", "*=", "/=", "%=", + "<<=", ">>=", ">>>=", + "|=", "^=", "&="); + +def("AssignmentExpression") + .bases("Expression") + .build("operator", "left", "right") + .field("operator", AssignmentOperator) + .field("left", def("Pattern")) + .field("right", def("Expression")); + +var UpdateOperator = or("++", "--"); + +def("UpdateExpression") + .bases("Expression") + .build("operator", "argument", "prefix") + .field("operator", UpdateOperator) + .field("argument", def("Expression")) + .field("prefix", Boolean); + +var LogicalOperator = or("||", "&&"); + +def("LogicalExpression") + .bases("Expression") + .build("operator", "left", "right") + .field("operator", LogicalOperator) + .field("left", def("Expression")) + .field("right", def("Expression")); + +def("ConditionalExpression") + .bases("Expression") + .build("test", "consequent", "alternate") + .field("test", def("Expression")) + .field("consequent", def("Expression")) + .field("alternate", def("Expression")); + +def("NewExpression") + .bases("Expression") + .build("callee", "arguments") + .field("callee", def("Expression")) + // The Mozilla Parser API gives this type as [or(def("Expression"), + // null)], but null values don't really make sense at the call site. + // TODO Report this nonsense. + .field("arguments", [def("Expression")]); + +def("CallExpression") + .bases("Expression") + .build("callee", "arguments") + .field("callee", def("Expression")) + // See comment for NewExpression above. + .field("arguments", [def("Expression")]); + +def("MemberExpression") + .bases("Expression") + .build("object", "property", "computed") + .field("object", def("Expression")) + .field("property", or(def("Identifier"), def("Expression"))) + .field("computed", Boolean, defaults["false"]); + +def("Pattern").bases("Node"); + +def("SwitchCase") + .bases("Node") + .build("test", "consequent") + .field("test", or(def("Expression"), null)) + .field("consequent", [def("Statement")]); + +def("Identifier") + // But aren't Expressions and Patterns already Nodes? TODO Report this. + .bases("Node", "Expression", "Pattern") + .build("name") + .field("name", String); + +def("Literal") + // But aren't Expressions already Nodes? TODO Report this. + .bases("Node", "Expression") + .build("value") + .field("value", or(String, Boolean, null, Number, RegExp)) + .field("regex", or({ + pattern: String, + flags: String + }, null), function() { + if (this.value instanceof RegExp) { + var flags = ""; + + if (this.value.ignoreCase) flags += "i"; + if (this.value.multiline) flags += "m"; + if (this.value.global) flags += "g"; + + return { + pattern: this.value.source, + flags: flags + }; + } + + return null; + }); + +// Abstract (non-buildable) comment supertype. Not a Node. +def("Comment") + .bases("Printable") + .field("value", String) + // A .leading comment comes before the node, whereas a .trailing + // comment comes after it. These two fields should not both be true, + // but they might both be false when the comment falls inside a node + // and the node has no children for the comment to lead or trail, + // e.g. { /*dangling*/ }. + .field("leading", Boolean, defaults["true"]) + .field("trailing", Boolean, defaults["false"]); diff --git a/def/e4x.js b/def/e4x.js new file mode 100644 index 0000000..22ac0ff --- /dev/null +++ b/def/e4x.js @@ -0,0 +1,84 @@ +require("./core"); +var types = require("../lib/types"); +var def = types.Type.def; +var or = types.Type.or; + +// Note that none of these types are buildable because the Mozilla Parser +// API doesn't specify any builder functions, and nobody uses E4X anymore. + +def("XMLDefaultDeclaration") + .bases("Declaration") + .field("namespace", def("Expression")); + +def("XMLAnyName").bases("Expression"); + +def("XMLQualifiedIdentifier") + .bases("Expression") + .field("left", or(def("Identifier"), def("XMLAnyName"))) + .field("right", or(def("Identifier"), def("Expression"))) + .field("computed", Boolean); + +def("XMLFunctionQualifiedIdentifier") + .bases("Expression") + .field("right", or(def("Identifier"), def("Expression"))) + .field("computed", Boolean); + +def("XMLAttributeSelector") + .bases("Expression") + .field("attribute", def("Expression")); + +def("XMLFilterExpression") + .bases("Expression") + .field("left", def("Expression")) + .field("right", def("Expression")); + +def("XMLElement") + .bases("XML", "Expression") + .field("contents", [def("XML")]); + +def("XMLList") + .bases("XML", "Expression") + .field("contents", [def("XML")]); + +def("XML").bases("Node"); + +def("XMLEscape") + .bases("XML") + .field("expression", def("Expression")); + +def("XMLText") + .bases("XML") + .field("text", String); + +def("XMLStartTag") + .bases("XML") + .field("contents", [def("XML")]); + +def("XMLEndTag") + .bases("XML") + .field("contents", [def("XML")]); + +def("XMLPointTag") + .bases("XML") + .field("contents", [def("XML")]); + +def("XMLName") + .bases("XML") + .field("contents", or(String, [def("XML")])); + +def("XMLAttribute") + .bases("XML") + .field("value", String); + +def("XMLCdata") + .bases("XML") + .field("contents", String); + +def("XMLComment") + .bases("XML") + .field("contents", String); + +def("XMLProcessingInstruction") + .bases("XML") + .field("target", String) + .field("contents", or(String, null)); diff --git a/def/es6.js b/def/es6.js new file mode 100644 index 0000000..b73bc07 --- /dev/null +++ b/def/es6.js @@ -0,0 +1,217 @@ +require("./core"); +var types = require("../lib/types"); +var def = types.Type.def; +var or = types.Type.or; +var defaults = require("../lib/shared").defaults; + +def("Function") + .field("generator", Boolean, defaults["false"]) + .field("expression", Boolean, defaults["false"]) + .field("defaults", [or(def("Expression"), null)], defaults.emptyArray) + // TODO This could be represented as a RestElement in .params. + .field("rest", or(def("Identifier"), null), defaults["null"]); + +// The ESTree way of representing a ...rest parameter. +def("RestElement") + .bases("Pattern") + .build("argument") + .field("argument", def("Pattern")); + +def("SpreadElementPattern") + .bases("Pattern") + .build("argument") + .field("argument", def("Pattern")); + +def("FunctionDeclaration") + .build("id", "params", "body", "generator", "expression"); + +def("FunctionExpression") + .build("id", "params", "body", "generator", "expression"); + +// The Parser API calls this ArrowExpression, but Esprima and all other +// actual parsers use ArrowFunctionExpression. +def("ArrowFunctionExpression") + .bases("Function", "Expression") + .build("params", "body", "expression") + // The forced null value here is compatible with the overridden + // definition of the "id" field in the Function interface. + .field("id", null, defaults["null"]) + // Arrow function bodies are allowed to be expressions. + .field("body", or(def("BlockStatement"), def("Expression"))) + // The current spec forbids arrow generators, so I have taken the + // liberty of enforcing that. TODO Report this. + .field("generator", false, defaults["false"]); + +def("YieldExpression") + .bases("Expression") + .build("argument", "delegate") + .field("argument", or(def("Expression"), null)) + .field("delegate", Boolean, defaults["false"]); + +def("GeneratorExpression") + .bases("Expression") + .build("body", "blocks", "filter") + .field("body", def("Expression")) + .field("blocks", [def("ComprehensionBlock")]) + .field("filter", or(def("Expression"), null)); + +def("ComprehensionExpression") + .bases("Expression") + .build("body", "blocks", "filter") + .field("body", def("Expression")) + .field("blocks", [def("ComprehensionBlock")]) + .field("filter", or(def("Expression"), null)); + +def("ComprehensionBlock") + .bases("Node") + .build("left", "right", "each") + .field("left", def("Pattern")) + .field("right", def("Expression")) + .field("each", Boolean); + +def("Property") + .field("key", or(def("Literal"), def("Identifier"), def("Expression"))) + .field("value", or(def("Expression"), def("Pattern"))) + .field("method", Boolean, defaults["false"]) + .field("shorthand", Boolean, defaults["false"]) + .field("computed", Boolean, defaults["false"]); + +def("PropertyPattern") + .bases("Pattern") + .build("key", "pattern") + .field("key", or(def("Literal"), def("Identifier"), def("Expression"))) + .field("pattern", def("Pattern")) + .field("computed", Boolean, defaults["false"]); + +def("ObjectPattern") + .bases("Pattern") + .build("properties") + .field("properties", [or(def("PropertyPattern"), def("Property"))]); + +def("ArrayPattern") + .bases("Pattern") + .build("elements") + .field("elements", [or(def("Pattern"), null)]); + +def("MethodDefinition") + .bases("Declaration") + .build("kind", "key", "value", "static") + .field("kind", or("constructor", "method", "get", "set")) + .field("key", or(def("Literal"), def("Identifier"), def("Expression"))) + .field("value", def("Function")) + .field("computed", Boolean, defaults["false"]) + .field("static", Boolean, defaults["false"]); + +def("SpreadElement") + .bases("Node") + .build("argument") + .field("argument", def("Expression")); + +def("ArrayExpression") + .field("elements", [or( + def("Expression"), + def("SpreadElement"), + def("RestElement"), + null + )]); + +def("NewExpression") + .field("arguments", [or(def("Expression"), def("SpreadElement"))]); + +def("CallExpression") + .field("arguments", [or(def("Expression"), def("SpreadElement"))]); + +// Note: this node type is *not* an AssignmentExpression with a Pattern on +// the left-hand side! The existing AssignmentExpression type already +// supports destructuring assignments. AssignmentPattern nodes may appear +// wherever a Pattern is allowed, and the right-hand side represents a +// default value to be destructured against the left-hand side, if no +// value is otherwise provided. For example: default parameter values. +def("AssignmentPattern") + .bases("Pattern") + .build("left", "right") + .field("left", def("Pattern")) + .field("right", def("Expression")); + +var ClassBodyElement = or( + def("MethodDefinition"), + def("VariableDeclarator"), + def("ClassPropertyDefinition"), + def("ClassProperty") +); + +def("ClassProperty") + .bases("Declaration") + .build("key") + .field("key", or(def("Literal"), def("Identifier"), def("Expression"))) + .field("computed", Boolean, defaults["false"]); + +def("ClassPropertyDefinition") // static property + .bases("Declaration") + .build("definition") + // Yes, Virginia, circular definitions are permitted. + .field("definition", ClassBodyElement); + +def("ClassBody") + .bases("Declaration") + .build("body") + .field("body", [ClassBodyElement]); + +def("ClassDeclaration") + .bases("Declaration") + .build("id", "body", "superClass") + .field("id", or(def("Identifier"), null)) + .field("body", def("ClassBody")) + .field("superClass", or(def("Expression"), null), defaults["null"]); + +def("ClassExpression") + .bases("Expression") + .build("id", "body", "superClass") + .field("id", or(def("Identifier"), null), defaults["null"]) + .field("body", def("ClassBody")) + .field("superClass", or(def("Expression"), null), defaults["null"]) + .field("implements", [def("ClassImplements")], defaults.emptyArray); + +def("ClassImplements") + .bases("Node") + .build("id") + .field("id", def("Identifier")) + .field("superClass", or(def("Expression"), null), defaults["null"]); + +// Specifier and ModuleSpecifier are abstract non-standard types +// introduced for definitional convenience. +def("Specifier").bases("Node"); + +// This supertype is shared/abused by both def/babel.js and +// def/esprima.js. In the future, it will be possible to load only one set +// of definitions appropriate for a given parser, but until then we must +// rely on default functions to reconcile the conflicting AST formats. +def("ModuleSpecifier") + .bases("Specifier") + // This local field is used by Babel/Acorn. It should not technically + // be optional in the Babel/Acorn AST format, but it must be optional + // in the Esprima AST format. + .field("local", or(def("Identifier"), null), defaults["null"]) + // The id and name fields are used by Esprima. The id field should not + // technically be optional in the Esprima AST format, but it must be + // optional in the Babel/Acorn AST format. + .field("id", or(def("Identifier"), null), defaults["null"]) + .field("name", or(def("Identifier"), null), defaults["null"]); + +def("TaggedTemplateExpression") + .bases("Expression") + .build("tag", "quasi") + .field("tag", def("Expression")) + .field("quasi", def("TemplateLiteral")); + +def("TemplateLiteral") + .bases("Expression") + .build("quasis", "expressions") + .field("quasis", [def("TemplateElement")]) + .field("expressions", [def("Expression")]); + +def("TemplateElement") + .bases("Node") + .build("value", "tail") + .field("value", {"cooked": String, "raw": String}) + .field("tail", Boolean); diff --git a/def/es7.js b/def/es7.js new file mode 100644 index 0000000..e9c50bd --- /dev/null +++ b/def/es7.js @@ -0,0 +1,36 @@ +require("./es6"); + +var types = require("../lib/types"); +var def = types.Type.def; +var or = types.Type.or; +var builtin = types.builtInTypes; +var defaults = require("../lib/shared").defaults; + +def("Function") + .field("async", Boolean, defaults["false"]); + +def("SpreadProperty") + .bases("Node") + .build("argument") + .field("argument", def("Expression")); + +def("ObjectExpression") + .field("properties", [or(def("Property"), def("SpreadProperty"))]); + +def("SpreadPropertyPattern") + .bases("Pattern") + .build("argument") + .field("argument", def("Pattern")); + +def("ObjectPattern") + .field("properties", [or( + def("Property"), + def("PropertyPattern"), + def("SpreadPropertyPattern") + )]); + +def("AwaitExpression") + .bases("Expression") + .build("argument", "all") + .field("argument", or(def("Expression"), null)) + .field("all", Boolean, defaults["false"]); diff --git a/def/esprima.js b/def/esprima.js new file mode 100644 index 0000000..a27e38f --- /dev/null +++ b/def/esprima.js @@ -0,0 +1,96 @@ +require("./es7"); + +var types = require("../lib/types"); +var defaults = require("../lib/shared").defaults; +var def = types.Type.def; +var or = types.Type.or; + +def("VariableDeclaration") + .field("declarations", [or( + def("VariableDeclarator"), + def("Identifier") // Esprima deviation. + )]); + +def("Property") + .field("value", or( + def("Expression"), + def("Pattern") // Esprima deviation. + )); + +def("ArrayPattern") + .field("elements", [or( + def("Pattern"), + def("SpreadElement"), + null + )]); + +def("ObjectPattern") + .field("properties", [or( + def("Property"), + def("PropertyPattern"), + def("SpreadPropertyPattern"), + def("SpreadProperty") // Used by Esprima. + )]); + +// Like ModuleSpecifier, except type:"ExportSpecifier" and buildable. +// export {} [from ...]; +def("ExportSpecifier") + .bases("ModuleSpecifier") + .build("id", "name"); + +// export <*> from ...; +def("ExportBatchSpecifier") + .bases("Specifier") + .build(); + +// Like ModuleSpecifier, except type:"ImportSpecifier" and buildable. +// import {} from ...; +def("ImportSpecifier") + .bases("ModuleSpecifier") + .build("id", "name"); + +// import <* as id> from ...; +def("ImportNamespaceSpecifier") + .bases("ModuleSpecifier") + .build("id"); + +// import from ...; +def("ImportDefaultSpecifier") + .bases("ModuleSpecifier") + .build("id"); + +def("ExportDeclaration") + .bases("Declaration") + .build("default", "declaration", "specifiers", "source") + .field("default", Boolean) + .field("declaration", or( + def("Declaration"), + def("Expression"), // Implies default. + null + )) + .field("specifiers", [or( + def("ExportSpecifier"), + def("ExportBatchSpecifier") + )], defaults.emptyArray) + .field("source", or( + def("Literal"), + null + ), defaults["null"]); + +def("ImportDeclaration") + .bases("Declaration") + .build("specifiers", "source") + .field("specifiers", [or( + def("ImportSpecifier"), + def("ImportNamespaceSpecifier"), + def("ImportDefaultSpecifier") + )], defaults.emptyArray) + .field("source", def("Literal")); + +def("Block") + .bases("Comment") + .build("value", /*optional:*/ "leading", "trailing"); + +def("Line") + .bases("Comment") + .build("value", /*optional:*/ "leading", "trailing"); diff --git a/def/fb-harmony.js b/def/fb-harmony.js new file mode 100644 index 0000000..3527be5 --- /dev/null +++ b/def/fb-harmony.js @@ -0,0 +1,327 @@ +require("./es7"); + +var types = require("../lib/types"); +var def = types.Type.def; +var or = types.Type.or; +var defaults = require("../lib/shared").defaults; + +def("JSXAttribute") + .bases("Node") + .build("name", "value") + .field("name", or(def("JSXIdentifier"), def("JSXNamespacedName"))) + .field("value", or( + def("Literal"), // attr="value" + def("JSXExpressionContainer"), // attr={value} + null // attr= or just attr + ), defaults["null"]); + +def("JSXIdentifier") + .bases("Identifier") + .build("name") + .field("name", String); + +def("JSXNamespacedName") + .bases("Node") + .build("namespace", "name") + .field("namespace", def("JSXIdentifier")) + .field("name", def("JSXIdentifier")); + +def("JSXMemberExpression") + .bases("MemberExpression") + .build("object", "property") + .field("object", or(def("JSXIdentifier"), def("JSXMemberExpression"))) + .field("property", def("JSXIdentifier")) + .field("computed", Boolean, defaults.false); + +var JSXElementName = or( + def("JSXIdentifier"), + def("JSXNamespacedName"), + def("JSXMemberExpression") +); + +def("JSXSpreadAttribute") + .bases("Node") + .build("argument") + .field("argument", def("Expression")); + +var JSXAttributes = [or( + def("JSXAttribute"), + def("JSXSpreadAttribute") +)]; + +def("JSXExpressionContainer") + .bases("Expression") + .build("expression") + .field("expression", def("Expression")); + +def("JSXElement") + .bases("Expression") + .build("openingElement", "closingElement", "children") + .field("openingElement", def("JSXOpeningElement")) + .field("closingElement", or(def("JSXClosingElement"), null), defaults["null"]) + .field("children", [or( + def("JSXElement"), + def("JSXExpressionContainer"), + def("JSXText"), + def("Literal") // TODO Esprima should return JSXText instead. + )], defaults.emptyArray) + .field("name", JSXElementName, function() { + // Little-known fact: the `this` object inside a default function + // is none other than the partially-built object itself, and any + // fields initialized directly from builder function arguments + // (like openingElement, closingElement, and children) are + // guaranteed to be available. + return this.openingElement.name; + }, true) // hidden from traversal + .field("selfClosing", Boolean, function() { + return this.openingElement.selfClosing; + }, true) // hidden from traversal + .field("attributes", JSXAttributes, function() { + return this.openingElement.attributes; + }, true); // hidden from traversal + +def("JSXOpeningElement") + .bases("Node") // TODO Does this make sense? Can't really be an JSXElement. + .build("name", "attributes", "selfClosing") + .field("name", JSXElementName) + .field("attributes", JSXAttributes, defaults.emptyArray) + .field("selfClosing", Boolean, defaults["false"]); + +def("JSXClosingElement") + .bases("Node") // TODO Same concern. + .build("name") + .field("name", JSXElementName); + +def("JSXText") + .bases("Literal") + .build("value") + .field("value", String); + +def("JSXEmptyExpression").bases("Expression").build(); + +// Type Annotations +def("Type").bases("Node"); + +def("AnyTypeAnnotation") + .bases("Type") + .build(); + +def("MixedTypeAnnotation") + .bases("Type") + .build(); + +def("VoidTypeAnnotation") + .bases("Type") + .build(); + +def("NumberTypeAnnotation") + .bases("Type") + .build(); + +def("NumberLiteralTypeAnnotation") + .bases("Type") + .build("value", "raw") + .field("value", Number) + .field("raw", String); + +def("StringTypeAnnotation") + .bases("Type") + .build(); + +def("StringLiteralTypeAnnotation") + .bases("Type") + .build("value", "raw") + .field("value", String) + .field("raw", String); + +def("BooleanTypeAnnotation") + .bases("Type") + .build(); + +def("BooleanLiteralTypeAnnotation") + .bases("Type") + .build("value", "raw") + .field("value", Boolean) + .field("raw", String); + +def("TypeAnnotation") + .bases("Node") + .build("typeAnnotation") + .field("typeAnnotation", def("Type")); + +def("NullableTypeAnnotation") + .bases("Type") + .build("typeAnnotation") + .field("typeAnnotation", def("Type")); + +def("FunctionTypeAnnotation") + .bases("Type") + .build("params", "returnType", "rest", "typeParameters") + .field("params", [def("FunctionTypeParam")]) + .field("returnType", def("Type")) + .field("rest", or(def("FunctionTypeParam"), null)) + .field("typeParameters", or(def("TypeParameterDeclaration"), null)); + +def("FunctionTypeParam") + .bases("Node") + .build("name", "typeAnnotation", "optional") + .field("name", def("Identifier")) + .field("typeAnnotation", def("Type")) + .field("optional", Boolean); + +def("ArrayTypeAnnotation") + .bases("Type") + .build("elementType") + .field("elementType", def("Type")); + +def("ObjectTypeAnnotation") + .bases("Type") + .build("properties") + .field("properties", [def("ObjectTypeProperty")]) + .field("indexers", [def("ObjectTypeIndexer")], defaults.emptyArray) + .field("callProperties", + [def("ObjectTypeCallProperty")], + defaults.emptyArray); + +def("ObjectTypeProperty") + .bases("Node") + .build("key", "value", "optional") + .field("key", or(def("Literal"), def("Identifier"))) + .field("value", def("Type")) + .field("optional", Boolean); + +def("ObjectTypeIndexer") + .bases("Node") + .build("id", "key", "value") + .field("id", def("Identifier")) + .field("key", def("Type")) + .field("value", def("Type")); + +def("ObjectTypeCallProperty") + .bases("Node") + .build("value") + .field("value", def("FunctionTypeAnnotation")) + .field("static", Boolean, false); + +def("QualifiedTypeIdentifier") + .bases("Node") + .build("qualification", "id") + .field("qualification", + or(def("Identifier"), + def("QualifiedTypeIdentifier"))) + .field("id", def("Identifier")); + +def("GenericTypeAnnotation") + .bases("Type") + .build("id", "typeParameters") + .field("id", or(def("Identifier"), def("QualifiedTypeIdentifier"))) + .field("typeParameters", or(def("TypeParameterInstantiation"), null)); + +def("MemberTypeAnnotation") + .bases("Type") + .build("object", "property") + .field("object", def("Identifier")) + .field("property", + or(def("MemberTypeAnnotation"), + def("GenericTypeAnnotation"))); + +def("UnionTypeAnnotation") + .bases("Type") + .build("types") + .field("types", [def("Type")]); + +def("IntersectionTypeAnnotation") + .bases("Type") + .build("types") + .field("types", [def("Type")]); + +def("TypeofTypeAnnotation") + .bases("Type") + .build("argument") + .field("argument", def("Type")); + +def("Identifier") + .field("typeAnnotation", or(def("TypeAnnotation"), null), defaults["null"]); + +def("TypeParameterDeclaration") + .bases("Node") + .build("params") + .field("params", [def("Identifier")]); + +def("TypeParameterInstantiation") + .bases("Node") + .build("params") + .field("params", [def("Type")]); + +def("Function") + .field("returnType", + or(def("TypeAnnotation"), null), + defaults["null"]) + .field("typeParameters", + or(def("TypeParameterDeclaration"), null), + defaults["null"]); + +def("ClassProperty") + .build("key", "value", "typeAnnotation", "static") + .field("value", or(def("Expression"), null)) + .field("typeAnnotation", or(def("TypeAnnotation"), null)) + .field("static", Boolean, defaults["false"]); + +def("ClassImplements") + .field("typeParameters", + or(def("TypeParameterInstantiation"), null), + defaults["null"]); + +def("InterfaceDeclaration") + .bases("Statement") + .build("id", "body", "extends") + .field("id", def("Identifier")) + .field("typeParameters", + or(def("TypeParameterDeclaration"), null), + defaults["null"]) + .field("body", def("ObjectTypeAnnotation")) + .field("extends", [def("InterfaceExtends")]); + +def("InterfaceExtends") + .bases("Node") + .build("id") + .field("id", def("Identifier")) + .field("typeParameters", or(def("TypeParameterInstantiation"), null)); + +def("TypeAlias") + .bases("Declaration") + .build("id", "typeParameters", "right") + .field("id", def("Identifier")) + .field("typeParameters", or(def("TypeParameterDeclaration"), null)) + .field("right", def("Type")); + +def("TypeCastExpression") + .bases("Expression") + .build("expression", "typeAnnotation") + .field("expression", def("Expression")) + .field("typeAnnotation", def("TypeAnnotation")); + +def("TupleTypeAnnotation") + .bases("Type") + .build("types") + .field("types", [def("Type")]); + +def("DeclareVariable") + .bases("Statement") + .build("id") + .field("id", def("Identifier")); + +def("DeclareFunction") + .bases("Statement") + .build("id") + .field("id", def("Identifier")); + +def("DeclareClass") + .bases("InterfaceDeclaration") + .build("id"); + +def("DeclareModule") + .bases("Statement") + .build("id", "body") + .field("id", or(def("Identifier"), def("Literal"))) + .field("body", def("BlockStatement")); diff --git a/def/mozilla.js b/def/mozilla.js new file mode 100644 index 0000000..2861ae9 --- /dev/null +++ b/def/mozilla.js @@ -0,0 +1,49 @@ +require("./core"); +var types = require("../lib/types"); +var def = types.Type.def; +var or = types.Type.or; +var shared = require("../lib/shared"); +var geq = shared.geq; +var defaults = shared.defaults; + +def("Function") + // SpiderMonkey allows expression closures: function(x) x+1 + .field("body", or(def("BlockStatement"), def("Expression"))); + +def("ForInStatement") + .build("left", "right", "body", "each") + .field("each", Boolean, defaults["false"]); + +def("ForOfStatement") + .bases("Statement") + .build("left", "right", "body") + .field("left", or( + def("VariableDeclaration"), + def("Expression"))) + .field("right", def("Expression")) + .field("body", def("Statement")); + +def("LetStatement") + .bases("Statement") + .build("head", "body") + // TODO Deviating from the spec by reusing VariableDeclarator here. + .field("head", [def("VariableDeclarator")]) + .field("body", def("Statement")); + +def("LetExpression") + .bases("Expression") + .build("head", "body") + // TODO Deviating from the spec by reusing VariableDeclarator here. + .field("head", [def("VariableDeclarator")]) + .field("body", def("Expression")); + +def("GraphExpression") + .bases("Expression") + .build("index", "expression") + .field("index", geq(0)) + .field("expression", def("Literal")); + +def("GraphIndexExpression") + .bases("Expression") + .build("index") + .field("index", geq(0)); diff --git a/lib/equiv.js b/lib/equiv.js new file mode 100644 index 0000000..6167577 --- /dev/null +++ b/lib/equiv.js @@ -0,0 +1,184 @@ +var types = require("../main"); +var getFieldNames = types.getFieldNames; +var getFieldValue = types.getFieldValue; +var isArray = types.builtInTypes.array; +var isObject = types.builtInTypes.object; +var isDate = types.builtInTypes.Date; +var isRegExp = types.builtInTypes.RegExp; +var hasOwn = Object.prototype.hasOwnProperty; + +function astNodesAreEquivalent(a, b, problemPath) { + if (isArray.check(problemPath)) { + problemPath.length = 0; + } else { + problemPath = null; + } + + return areEquivalent(a, b, problemPath); +} + +astNodesAreEquivalent.assert = function(a, b) { + var problemPath = []; + if (!astNodesAreEquivalent(a, b, problemPath)) { + if (problemPath.length === 0) { + if (a !== b) { + throw new Error("Nodes must be equal"); + } + } else { + throw new Error( + "Nodes differ in the following path: " + + problemPath.map(subscriptForProperty).join("") + ); + } + } +}; + +function subscriptForProperty(property) { + if (/[_$a-z][_$a-z0-9]*/i.test(property)) { + return "." + property; + } + return "[" + JSON.stringify(property) + "]"; +} + +function areEquivalent(a, b, problemPath) { + if (a === b) { + return true; + } + + if (isArray.check(a)) { + return arraysAreEquivalent(a, b, problemPath); + } + + if (isObject.check(a)) { + return objectsAreEquivalent(a, b, problemPath); + } + + if (isDate.check(a)) { + return isDate.check(b) && (+a === +b); + } + + if (isRegExp.check(a)) { + return isRegExp.check(b) && ( + a.source === b.source && + a.global === b.global && + a.multiline === b.multiline && + a.ignoreCase === b.ignoreCase + ); + } + + return a == b; +} + +function arraysAreEquivalent(a, b, problemPath) { + isArray.assert(a); + var aLength = a.length; + + if (!isArray.check(b) || b.length !== aLength) { + if (problemPath) { + problemPath.push("length"); + } + return false; + } + + for (var i = 0; i < aLength; ++i) { + if (problemPath) { + problemPath.push(i); + } + + if (i in a !== i in b) { + return false; + } + + if (!areEquivalent(a[i], b[i], problemPath)) { + return false; + } + + if (problemPath) { + var problemPathTail = problemPath.pop(); + if (problemPathTail !== i) { + throw new Error("" + problemPathTail); + } + } + } + + return true; +} + +function objectsAreEquivalent(a, b, problemPath) { + isObject.assert(a); + if (!isObject.check(b)) { + return false; + } + + // Fast path for a common property of AST nodes. + if (a.type !== b.type) { + if (problemPath) { + problemPath.push("type"); + } + return false; + } + + var aNames = getFieldNames(a); + var aNameCount = aNames.length; + + var bNames = getFieldNames(b); + var bNameCount = bNames.length; + + if (aNameCount === bNameCount) { + for (var i = 0; i < aNameCount; ++i) { + var name = aNames[i]; + var aChild = getFieldValue(a, name); + var bChild = getFieldValue(b, name); + + if (problemPath) { + problemPath.push(name); + } + + if (!areEquivalent(aChild, bChild, problemPath)) { + return false; + } + + if (problemPath) { + var problemPathTail = problemPath.pop(); + if (problemPathTail !== name) { + throw new Error("" + problemPathTail); + } + } + } + + return true; + } + + if (!problemPath) { + return false; + } + + // Since aNameCount !== bNameCount, we need to find some name that's + // missing in aNames but present in bNames, or vice-versa. + + var seenNames = Object.create(null); + + for (i = 0; i < aNameCount; ++i) { + seenNames[aNames[i]] = true; + } + + for (i = 0; i < bNameCount; ++i) { + name = bNames[i]; + + if (!hasOwn.call(seenNames, name)) { + problemPath.push(name); + return false; + } + + delete seenNames[name]; + } + + for (name in seenNames) { + problemPath.push(name); + break; + } + + return false; +} + +module.exports = astNodesAreEquivalent; diff --git a/lib/node-path.js b/lib/node-path.js new file mode 100644 index 0000000..fbb79ea --- /dev/null +++ b/lib/node-path.js @@ -0,0 +1,474 @@ +var types = require("./types"); +var n = types.namedTypes; +var b = types.builders; +var isNumber = types.builtInTypes.number; +var isArray = types.builtInTypes.array; +var Path = require("./path"); +var Scope = require("./scope"); + +function NodePath(value, parentPath, name) { + if (!(this instanceof NodePath)) { + throw new Error("NodePath constructor cannot be invoked without 'new'"); + } + Path.call(this, value, parentPath, name); +} + +var NPp = NodePath.prototype = Object.create(Path.prototype, { + constructor: { + value: NodePath, + enumerable: false, + writable: true, + configurable: true + } +}); + +Object.defineProperties(NPp, { + node: { + get: function() { + Object.defineProperty(this, "node", { + configurable: true, // Enable deletion. + value: this._computeNode() + }); + + return this.node; + } + }, + + parent: { + get: function() { + Object.defineProperty(this, "parent", { + configurable: true, // Enable deletion. + value: this._computeParent() + }); + + return this.parent; + } + }, + + scope: { + get: function() { + Object.defineProperty(this, "scope", { + configurable: true, // Enable deletion. + value: this._computeScope() + }); + + return this.scope; + } + } +}); + +NPp.replace = function() { + delete this.node; + delete this.parent; + delete this.scope; + return Path.prototype.replace.apply(this, arguments); +}; + +NPp.prune = function() { + var remainingNodePath = this.parent; + + this.replace(); + + return cleanUpNodesAfterPrune(remainingNodePath); +}; + +// The value of the first ancestor Path whose value is a Node. +NPp._computeNode = function() { + var value = this.value; + if (n.Node.check(value)) { + return value; + } + + var pp = this.parentPath; + return pp && pp.node || null; +}; + +// The first ancestor Path whose value is a Node distinct from this.node. +NPp._computeParent = function() { + var value = this.value; + var pp = this.parentPath; + + if (!n.Node.check(value)) { + while (pp && !n.Node.check(pp.value)) { + pp = pp.parentPath; + } + + if (pp) { + pp = pp.parentPath; + } + } + + while (pp && !n.Node.check(pp.value)) { + pp = pp.parentPath; + } + + return pp || null; +}; + +// The closest enclosing scope that governs this node. +NPp._computeScope = function() { + var value = this.value; + var pp = this.parentPath; + var scope = pp && pp.scope; + + if (n.Node.check(value) && + Scope.isEstablishedBy(value)) { + scope = new Scope(this, scope); + } + + return scope || null; +}; + +NPp.getValueProperty = function(name) { + return types.getFieldValue(this.value, name); +}; + +/** + * Determine whether this.node needs to be wrapped in parentheses in order + * for a parser to reproduce the same local AST structure. + * + * For instance, in the expression `(1 + 2) * 3`, the BinaryExpression + * whose operator is "+" needs parentheses, because `1 + 2 * 3` would + * parse differently. + * + * If assumeExpressionContext === true, we don't worry about edge cases + * like an anonymous FunctionExpression appearing lexically first in its + * enclosing statement and thus needing parentheses to avoid being parsed + * as a FunctionDeclaration with a missing name. + */ +NPp.needsParens = function(assumeExpressionContext) { + var pp = this.parentPath; + if (!pp) { + return false; + } + + var node = this.value; + + // Only expressions need parentheses. + if (!n.Expression.check(node)) { + return false; + } + + // Identifiers never need parentheses. + if (node.type === "Identifier") { + return false; + } + + while (!n.Node.check(pp.value)) { + pp = pp.parentPath; + if (!pp) { + return false; + } + } + + var parent = pp.value; + + switch (node.type) { + case "UnaryExpression": + case "SpreadElement": + case "SpreadProperty": + return parent.type === "MemberExpression" + && this.name === "object" + && parent.object === node; + + case "BinaryExpression": + case "LogicalExpression": + switch (parent.type) { + case "CallExpression": + return this.name === "callee" + && parent.callee === node; + + case "UnaryExpression": + case "SpreadElement": + case "SpreadProperty": + return true; + + case "MemberExpression": + return this.name === "object" + && parent.object === node; + + case "BinaryExpression": + case "LogicalExpression": + var po = parent.operator; + var pp = PRECEDENCE[po]; + var no = node.operator; + var np = PRECEDENCE[no]; + + if (pp > np) { + return true; + } + + if (pp === np && this.name === "right") { + if (parent.right !== node) { + throw new Error("Nodes must be equal"); + } + return true; + } + + default: + return false; + } + + case "SequenceExpression": + switch (parent.type) { + case "ForStatement": + // Although parentheses wouldn't hurt around sequence + // expressions in the head of for loops, traditional style + // dictates that e.g. i++, j++ should not be wrapped with + // parentheses. + return false; + + case "ExpressionStatement": + return this.name !== "expression"; + + default: + // Otherwise err on the side of overparenthesization, adding + // explicit exceptions above if this proves overzealous. + return true; + } + + case "YieldExpression": + switch (parent.type) { + case "BinaryExpression": + case "LogicalExpression": + case "UnaryExpression": + case "SpreadElement": + case "SpreadProperty": + case "CallExpression": + case "MemberExpression": + case "NewExpression": + case "ConditionalExpression": + case "YieldExpression": + return true; + + default: + return false; + } + + case "Literal": + return parent.type === "MemberExpression" + && isNumber.check(node.value) + && this.name === "object" + && parent.object === node; + + case "AssignmentExpression": + case "ConditionalExpression": + switch (parent.type) { + case "UnaryExpression": + case "SpreadElement": + case "SpreadProperty": + case "BinaryExpression": + case "LogicalExpression": + return true; + + case "CallExpression": + return this.name === "callee" + && parent.callee === node; + + case "ConditionalExpression": + return this.name === "test" + && parent.test === node; + + case "MemberExpression": + return this.name === "object" + && parent.object === node; + + default: + return false; + } + + default: + if (parent.type === "NewExpression" && + this.name === "callee" && + parent.callee === node) { + return containsCallExpression(node); + } + } + + if (assumeExpressionContext !== true && + !this.canBeFirstInStatement() && + this.firstInStatement()) + return true; + + return false; +}; + +function isBinary(node) { + return n.BinaryExpression.check(node) + || n.LogicalExpression.check(node); +} + +function isUnaryLike(node) { + return n.UnaryExpression.check(node) + // I considered making SpreadElement and SpreadProperty subtypes + // of UnaryExpression, but they're not really Expression nodes. + || (n.SpreadElement && n.SpreadElement.check(node)) + || (n.SpreadProperty && n.SpreadProperty.check(node)); +} + +var PRECEDENCE = {}; +[["||"], + ["&&"], + ["|"], + ["^"], + ["&"], + ["==", "===", "!=", "!=="], + ["<", ">", "<=", ">=", "in", "instanceof"], + [">>", "<<", ">>>"], + ["+", "-"], + ["*", "/", "%"] +].forEach(function(tier, i) { + tier.forEach(function(op) { + PRECEDENCE[op] = i; + }); +}); + +function containsCallExpression(node) { + if (n.CallExpression.check(node)) { + return true; + } + + if (isArray.check(node)) { + return node.some(containsCallExpression); + } + + if (n.Node.check(node)) { + return types.someField(node, function(name, child) { + return containsCallExpression(child); + }); + } + + return false; +} + +NPp.canBeFirstInStatement = function() { + var node = this.node; + return !n.FunctionExpression.check(node) + && !n.ObjectExpression.check(node); +}; + +NPp.firstInStatement = function() { + return firstInStatement(this); +}; + +function firstInStatement(path) { + for (var node, parent; path.parent; path = path.parent) { + node = path.node; + parent = path.parent.node; + + if (n.BlockStatement.check(parent) && + path.parent.name === "body" && + path.name === 0) { + if (parent.body[0] !== node) { + throw new Error("Nodes must be equal"); + } + return true; + } + + if (n.ExpressionStatement.check(parent) && + path.name === "expression") { + if (parent.expression !== node) { + throw new Error("Nodes must be equal"); + } + return true; + } + + if (n.SequenceExpression.check(parent) && + path.parent.name === "expressions" && + path.name === 0) { + if (parent.expressions[0] !== node) { + throw new Error("Nodes must be equal"); + } + continue; + } + + if (n.CallExpression.check(parent) && + path.name === "callee") { + if (parent.callee !== node) { + throw new Error("Nodes must be equal"); + } + continue; + } + + if (n.MemberExpression.check(parent) && + path.name === "object") { + if (parent.object !== node) { + throw new Error("Nodes must be equal"); + } + continue; + } + + if (n.ConditionalExpression.check(parent) && + path.name === "test") { + if (parent.test !== node) { + throw new Error("Nodes must be equal"); + } + continue; + } + + if (isBinary(parent) && + path.name === "left") { + if (parent.left !== node) { + throw new Error("Nodes must be equal"); + } + continue; + } + + if (n.UnaryExpression.check(parent) && + !parent.prefix && + path.name === "argument") { + if (parent.argument !== node) { + throw new Error("Nodes must be equal"); + } + continue; + } + + return false; + } + + return true; +} + +/** + * Pruning certain nodes will result in empty or incomplete nodes, here we clean those nodes up. + */ +function cleanUpNodesAfterPrune(remainingNodePath) { + if (n.VariableDeclaration.check(remainingNodePath.node)) { + var declarations = remainingNodePath.get('declarations').value; + if (!declarations || declarations.length === 0) { + return remainingNodePath.prune(); + } + } else if (n.ExpressionStatement.check(remainingNodePath.node)) { + if (!remainingNodePath.get('expression').value) { + return remainingNodePath.prune(); + } + } else if (n.IfStatement.check(remainingNodePath.node)) { + cleanUpIfStatementAfterPrune(remainingNodePath); + } + + return remainingNodePath; +} + +function cleanUpIfStatementAfterPrune(ifStatement) { + var testExpression = ifStatement.get('test').value; + var alternate = ifStatement.get('alternate').value; + var consequent = ifStatement.get('consequent').value; + + if (!consequent && !alternate) { + var testExpressionStatement = b.expressionStatement(testExpression); + + ifStatement.replace(testExpressionStatement); + } else if (!consequent && alternate) { + var negatedTestExpression = b.unaryExpression('!', testExpression, true); + + if (n.UnaryExpression.check(testExpression) && testExpression.operator === '!') { + negatedTestExpression = testExpression.argument; + } + + ifStatement.get("test").replace(negatedTestExpression); + ifStatement.get("consequent").replace(alternate); + ifStatement.get("alternate").replace(); + } +} + +module.exports = NodePath; diff --git a/lib/path-visitor.js b/lib/path-visitor.js new file mode 100644 index 0000000..cfe1441 --- /dev/null +++ b/lib/path-visitor.js @@ -0,0 +1,419 @@ +var types = require("./types"); +var NodePath = require("./node-path"); +var Printable = types.namedTypes.Printable; +var isArray = types.builtInTypes.array; +var isObject = types.builtInTypes.object; +var isFunction = types.builtInTypes.function; +var hasOwn = Object.prototype.hasOwnProperty; +var undefined; + +function PathVisitor() { + if (!(this instanceof PathVisitor)) { + throw new Error( + "PathVisitor constructor cannot be invoked without 'new'" + ); + } + + // Permanent state. + this._reusableContextStack = []; + + this._methodNameTable = computeMethodNameTable(this); + this._shouldVisitComments = + hasOwn.call(this._methodNameTable, "Block") || + hasOwn.call(this._methodNameTable, "Line"); + + this.Context = makeContextConstructor(this); + + // State reset every time PathVisitor.prototype.visit is called. + this._visiting = false; + this._changeReported = false; +} + +function computeMethodNameTable(visitor) { + var typeNames = Object.create(null); + + for (var methodName in visitor) { + if (/^visit[A-Z]/.test(methodName)) { + typeNames[methodName.slice("visit".length)] = true; + } + } + + var supertypeTable = types.computeSupertypeLookupTable(typeNames); + var methodNameTable = Object.create(null); + + var typeNames = Object.keys(supertypeTable); + var typeNameCount = typeNames.length; + for (var i = 0; i < typeNameCount; ++i) { + var typeName = typeNames[i]; + methodName = "visit" + supertypeTable[typeName]; + if (isFunction.check(visitor[methodName])) { + methodNameTable[typeName] = methodName; + } + } + + return methodNameTable; +} + +PathVisitor.fromMethodsObject = function fromMethodsObject(methods) { + if (methods instanceof PathVisitor) { + return methods; + } + + if (!isObject.check(methods)) { + // An empty visitor? + return new PathVisitor; + } + + function Visitor() { + if (!(this instanceof Visitor)) { + throw new Error( + "Visitor constructor cannot be invoked without 'new'" + ); + } + PathVisitor.call(this); + } + + var Vp = Visitor.prototype = Object.create(PVp); + Vp.constructor = Visitor; + + extend(Vp, methods); + extend(Visitor, PathVisitor); + + isFunction.assert(Visitor.fromMethodsObject); + isFunction.assert(Visitor.visit); + + return new Visitor; +}; + +function extend(target, source) { + for (var property in source) { + if (hasOwn.call(source, property)) { + target[property] = source[property]; + } + } + + return target; +} + +PathVisitor.visit = function visit(node, methods) { + return PathVisitor.fromMethodsObject(methods).visit(node); +}; + +var PVp = PathVisitor.prototype; + +PVp.visit = function() { + if (this._visiting) { + throw new Error( + "Recursively calling visitor.visit(path) resets visitor state. " + + "Try this.visit(path) or this.traverse(path) instead." + ); + } + + // Private state that needs to be reset before every traversal. + this._visiting = true; + this._changeReported = false; + this._abortRequested = false; + + var argc = arguments.length; + var args = new Array(argc) + for (var i = 0; i < argc; ++i) { + args[i] = arguments[i]; + } + + if (!(args[0] instanceof NodePath)) { + args[0] = new NodePath({ root: args[0] }).get("root"); + } + + // Called with the same arguments as .visit. + this.reset.apply(this, args); + + try { + var root = this.visitWithoutReset(args[0]); + var didNotThrow = true; + } finally { + this._visiting = false; + + if (!didNotThrow && this._abortRequested) { + // If this.visitWithoutReset threw an exception and + // this._abortRequested was set to true, return the root of + // the AST instead of letting the exception propagate, so that + // client code does not have to provide a try-catch block to + // intercept the AbortRequest exception. Other kinds of + // exceptions will propagate without being intercepted and + // rethrown by a catch block, so their stacks will accurately + // reflect the original throwing context. + return args[0].value; + } + } + + return root; +}; + +PVp.AbortRequest = function AbortRequest() {}; +PVp.abort = function() { + var visitor = this; + visitor._abortRequested = true; + var request = new visitor.AbortRequest(); + + // If you decide to catch this exception and stop it from propagating, + // make sure to call its cancel method to avoid silencing other + // exceptions that might be thrown later in the traversal. + request.cancel = function() { + visitor._abortRequested = false; + }; + + throw request; +}; + +PVp.reset = function(path/*, additional arguments */) { + // Empty stub; may be reassigned or overridden by subclasses. +}; + +PVp.visitWithoutReset = function(path) { + if (this instanceof this.Context) { + // Since this.Context.prototype === this, there's a chance we + // might accidentally call context.visitWithoutReset. If that + // happens, re-invoke the method against context.visitor. + return this.visitor.visitWithoutReset(path); + } + + if (!(path instanceof NodePath)) { + throw new Error(""); + } + + var value = path.value; + + var methodName = value && + typeof value === "object" && + typeof value.type === "string" && + this._methodNameTable[value.type]; + + if (methodName) { + var context = this.acquireContext(path); + try { + return context.invokeVisitorMethod(methodName); + } finally { + this.releaseContext(context); + } + + } else { + // If there was no visitor method to call, visit the children of + // this node generically. + return visitChildren(path, this); + } +}; + +function visitChildren(path, visitor) { + if (!(path instanceof NodePath)) { + throw new Error(""); + } + if (!(visitor instanceof PathVisitor)) { + throw new Error(""); + } + + var value = path.value; + + if (isArray.check(value)) { + path.each(visitor.visitWithoutReset, visitor); + } else if (!isObject.check(value)) { + // No children to visit. + } else { + var childNames = types.getFieldNames(value); + + // The .comments field of the Node type is hidden, so we only + // visit it if the visitor defines visitBlock or visitLine, and + // value.comments is defined. + if (visitor._shouldVisitComments && + value.comments && + childNames.indexOf("comments") < 0) { + childNames.push("comments"); + } + + var childCount = childNames.length; + var childPaths = []; + + for (var i = 0; i < childCount; ++i) { + var childName = childNames[i]; + if (!hasOwn.call(value, childName)) { + value[childName] = types.getFieldValue(value, childName); + } + childPaths.push(path.get(childName)); + } + + for (var i = 0; i < childCount; ++i) { + visitor.visitWithoutReset(childPaths[i]); + } + } + + return path.value; +} + +PVp.acquireContext = function(path) { + if (this._reusableContextStack.length === 0) { + return new this.Context(path); + } + return this._reusableContextStack.pop().reset(path); +}; + +PVp.releaseContext = function(context) { + if (!(context instanceof this.Context)) { + throw new Error(""); + } + this._reusableContextStack.push(context); + context.currentPath = null; +}; + +PVp.reportChanged = function() { + this._changeReported = true; +}; + +PVp.wasChangeReported = function() { + return this._changeReported; +}; + +function makeContextConstructor(visitor) { + function Context(path) { + if (!(this instanceof Context)) { + throw new Error(""); + } + if (!(this instanceof PathVisitor)) { + throw new Error(""); + } + if (!(path instanceof NodePath)) { + throw new Error(""); + } + + Object.defineProperty(this, "visitor", { + value: visitor, + writable: false, + enumerable: true, + configurable: false + }); + + this.currentPath = path; + this.needToCallTraverse = true; + + Object.seal(this); + } + + if (!(visitor instanceof PathVisitor)) { + throw new Error(""); + } + + // Note that the visitor object is the prototype of Context.prototype, + // so all visitor methods are inherited by context objects. + var Cp = Context.prototype = Object.create(visitor); + + Cp.constructor = Context; + extend(Cp, sharedContextProtoMethods); + + return Context; +} + +// Every PathVisitor has a different this.Context constructor and +// this.Context.prototype object, but those prototypes can all use the +// same reset, invokeVisitorMethod, and traverse function objects. +var sharedContextProtoMethods = Object.create(null); + +sharedContextProtoMethods.reset = +function reset(path) { + if (!(this instanceof this.Context)) { + throw new Error(""); + } + if (!(path instanceof NodePath)) { + throw new Error(""); + } + + this.currentPath = path; + this.needToCallTraverse = true; + + return this; +}; + +sharedContextProtoMethods.invokeVisitorMethod = +function invokeVisitorMethod(methodName) { + if (!(this instanceof this.Context)) { + throw new Error(""); + } + if (!(this.currentPath instanceof NodePath)) { + throw new Error(""); + } + + var result = this.visitor[methodName].call(this, this.currentPath); + + if (result === false) { + // Visitor methods return false to indicate that they have handled + // their own traversal needs, and we should not complain if + // this.needToCallTraverse is still true. + this.needToCallTraverse = false; + + } else if (result !== undefined) { + // Any other non-undefined value returned from the visitor method + // is interpreted as a replacement value. + this.currentPath = this.currentPath.replace(result)[0]; + + if (this.needToCallTraverse) { + // If this.traverse still hasn't been called, visit the + // children of the replacement node. + this.traverse(this.currentPath); + } + } + + if (this.needToCallTraverse !== false) { + throw new Error( + "Must either call this.traverse or return false in " + methodName + ); + } + + var path = this.currentPath; + return path && path.value; +}; + +sharedContextProtoMethods.traverse = +function traverse(path, newVisitor) { + if (!(this instanceof this.Context)) { + throw new Error(""); + } + if (!(path instanceof NodePath)) { + throw new Error(""); + } + if (!(this.currentPath instanceof NodePath)) { + throw new Error(""); + } + + this.needToCallTraverse = false; + + return visitChildren(path, PathVisitor.fromMethodsObject( + newVisitor || this.visitor + )); +}; + +sharedContextProtoMethods.visit = +function visit(path, newVisitor) { + if (!(this instanceof this.Context)) { + throw new Error(""); + } + if (!(path instanceof NodePath)) { + throw new Error(""); + } + if (!(this.currentPath instanceof NodePath)) { + throw new Error(""); + } + + this.needToCallTraverse = false; + + return PathVisitor.fromMethodsObject( + newVisitor || this.visitor + ).visitWithoutReset(path); +}; + +sharedContextProtoMethods.reportChanged = function reportChanged() { + this.visitor.reportChanged(); +}; + +sharedContextProtoMethods.abort = function abort() { + this.needToCallTraverse = false; + this.visitor.abort(); +}; + +module.exports = PathVisitor; diff --git a/lib/path.js b/lib/path.js new file mode 100644 index 0000000..9601e88 --- /dev/null +++ b/lib/path.js @@ -0,0 +1,366 @@ +var Op = Object.prototype; +var hasOwn = Op.hasOwnProperty; +var types = require("./types"); +var isArray = types.builtInTypes.array; +var isNumber = types.builtInTypes.number; +var Ap = Array.prototype; +var slice = Ap.slice; +var map = Ap.map; + +function Path(value, parentPath, name) { + if (!(this instanceof Path)) { + throw new Error("Path constructor cannot be invoked without 'new'"); + } + + if (parentPath) { + if (!(parentPath instanceof Path)) { + throw new Error(""); + } + } else { + parentPath = null; + name = null; + } + + // The value encapsulated by this Path, generally equal to + // parentPath.value[name] if we have a parentPath. + this.value = value; + + // The immediate parent Path of this Path. + this.parentPath = parentPath; + + // The name of the property of parentPath.value through which this + // Path's value was reached. + this.name = name; + + // Calling path.get("child") multiple times always returns the same + // child Path object, for both performance and consistency reasons. + this.__childCache = null; +} + +var Pp = Path.prototype; + +function getChildCache(path) { + // Lazily create the child cache. This also cheapens cache + // invalidation, since you can just reset path.__childCache to null. + return path.__childCache || (path.__childCache = Object.create(null)); +} + +function getChildPath(path, name) { + var cache = getChildCache(path); + var actualChildValue = path.getValueProperty(name); + var childPath = cache[name]; + if (!hasOwn.call(cache, name) || + // Ensure consistency between cache and reality. + childPath.value !== actualChildValue) { + childPath = cache[name] = new path.constructor( + actualChildValue, path, name + ); + } + return childPath; +} + +// This method is designed to be overridden by subclasses that need to +// handle missing properties, etc. +Pp.getValueProperty = function getValueProperty(name) { + return this.value[name]; +}; + +Pp.get = function get(name) { + var path = this; + var names = arguments; + var count = names.length; + + for (var i = 0; i < count; ++i) { + path = getChildPath(path, names[i]); + } + + return path; +}; + +Pp.each = function each(callback, context) { + var childPaths = []; + var len = this.value.length; + var i = 0; + + // Collect all the original child paths before invoking the callback. + for (var i = 0; i < len; ++i) { + if (hasOwn.call(this.value, i)) { + childPaths[i] = this.get(i); + } + } + + // Invoke the callback on just the original child paths, regardless of + // any modifications made to the array by the callback. I chose these + // semantics over cleverly invoking the callback on new elements because + // this way is much easier to reason about. + context = context || this; + for (i = 0; i < len; ++i) { + if (hasOwn.call(childPaths, i)) { + callback.call(context, childPaths[i]); + } + } +}; + +Pp.map = function map(callback, context) { + var result = []; + + this.each(function(childPath) { + result.push(callback.call(this, childPath)); + }, context); + + return result; +}; + +Pp.filter = function filter(callback, context) { + var result = []; + + this.each(function(childPath) { + if (callback.call(this, childPath)) { + result.push(childPath); + } + }, context); + + return result; +}; + +function emptyMoves() {} +function getMoves(path, offset, start, end) { + isArray.assert(path.value); + + if (offset === 0) { + return emptyMoves; + } + + var length = path.value.length; + if (length < 1) { + return emptyMoves; + } + + var argc = arguments.length; + if (argc === 2) { + start = 0; + end = length; + } else if (argc === 3) { + start = Math.max(start, 0); + end = length; + } else { + start = Math.max(start, 0); + end = Math.min(end, length); + } + + isNumber.assert(start); + isNumber.assert(end); + + var moves = Object.create(null); + var cache = getChildCache(path); + + for (var i = start; i < end; ++i) { + if (hasOwn.call(path.value, i)) { + var childPath = path.get(i); + if (childPath.name !== i) { + throw new Error(""); + } + var newIndex = i + offset; + childPath.name = newIndex; + moves[newIndex] = childPath; + delete cache[i]; + } + } + + delete cache.length; + + return function() { + for (var newIndex in moves) { + var childPath = moves[newIndex]; + if (childPath.name !== +newIndex) { + throw new Error(""); + } + cache[newIndex] = childPath; + path.value[newIndex] = childPath.value; + } + }; +} + +Pp.shift = function shift() { + var move = getMoves(this, -1); + var result = this.value.shift(); + move(); + return result; +}; + +Pp.unshift = function unshift(node) { + var move = getMoves(this, arguments.length); + var result = this.value.unshift.apply(this.value, arguments); + move(); + return result; +}; + +Pp.push = function push(node) { + isArray.assert(this.value); + delete getChildCache(this).length + return this.value.push.apply(this.value, arguments); +}; + +Pp.pop = function pop() { + isArray.assert(this.value); + var cache = getChildCache(this); + delete cache[this.value.length - 1]; + delete cache.length; + return this.value.pop(); +}; + +Pp.insertAt = function insertAt(index, node) { + var argc = arguments.length; + var move = getMoves(this, argc - 1, index); + if (move === emptyMoves) { + return this; + } + + index = Math.max(index, 0); + + for (var i = 1; i < argc; ++i) { + this.value[index + i - 1] = arguments[i]; + } + + move(); + + return this; +}; + +Pp.insertBefore = function insertBefore(node) { + var pp = this.parentPath; + var argc = arguments.length; + var insertAtArgs = [this.name]; + for (var i = 0; i < argc; ++i) { + insertAtArgs.push(arguments[i]); + } + return pp.insertAt.apply(pp, insertAtArgs); +}; + +Pp.insertAfter = function insertAfter(node) { + var pp = this.parentPath; + var argc = arguments.length; + var insertAtArgs = [this.name + 1]; + for (var i = 0; i < argc; ++i) { + insertAtArgs.push(arguments[i]); + } + return pp.insertAt.apply(pp, insertAtArgs); +}; + +function repairRelationshipWithParent(path) { + if (!(path instanceof Path)) { + throw new Error(""); + } + + var pp = path.parentPath; + if (!pp) { + // Orphan paths have no relationship to repair. + return path; + } + + var parentValue = pp.value; + var parentCache = getChildCache(pp); + + // Make sure parentCache[path.name] is populated. + if (parentValue[path.name] === path.value) { + parentCache[path.name] = path; + } else if (isArray.check(parentValue)) { + // Something caused path.name to become out of date, so attempt to + // recover by searching for path.value in parentValue. + var i = parentValue.indexOf(path.value); + if (i >= 0) { + parentCache[path.name = i] = path; + } + } else { + // If path.value disagrees with parentValue[path.name], and + // path.name is not an array index, let path.value become the new + // parentValue[path.name] and update parentCache accordingly. + parentValue[path.name] = path.value; + parentCache[path.name] = path; + } + + if (parentValue[path.name] !== path.value) { + throw new Error(""); + } + if (path.parentPath.get(path.name) !== path) { + throw new Error(""); + } + + return path; +} + +Pp.replace = function replace(replacement) { + var results = []; + var parentValue = this.parentPath.value; + var parentCache = getChildCache(this.parentPath); + var count = arguments.length; + + repairRelationshipWithParent(this); + + if (isArray.check(parentValue)) { + var originalLength = parentValue.length; + var move = getMoves(this.parentPath, count - 1, this.name + 1); + + var spliceArgs = [this.name, 1]; + for (var i = 0; i < count; ++i) { + spliceArgs.push(arguments[i]); + } + + var splicedOut = parentValue.splice.apply(parentValue, spliceArgs); + + if (splicedOut[0] !== this.value) { + throw new Error(""); + } + if (parentValue.length !== (originalLength - 1 + count)) { + throw new Error(""); + } + + move(); + + if (count === 0) { + delete this.value; + delete parentCache[this.name]; + this.__childCache = null; + + } else { + if (parentValue[this.name] !== replacement) { + throw new Error(""); + } + + if (this.value !== replacement) { + this.value = replacement; + this.__childCache = null; + } + + for (i = 0; i < count; ++i) { + results.push(this.parentPath.get(this.name + i)); + } + + if (results[0] !== this) { + throw new Error(""); + } + } + + } else if (count === 1) { + if (this.value !== replacement) { + this.__childCache = null; + } + this.value = parentValue[this.name] = replacement; + results.push(this); + + } else if (count === 0) { + delete parentValue[this.name]; + delete this.value; + this.__childCache = null; + + // Leave this path cached as parentCache[this.name], even though + // it no longer has a value defined. + + } else { + throw new Error("Could not replace path"); + } + + return results; +}; + +module.exports = Path; diff --git a/lib/scope.js b/lib/scope.js new file mode 100644 index 0000000..34ae1f1 --- /dev/null +++ b/lib/scope.js @@ -0,0 +1,295 @@ +var types = require("./types"); +var Type = types.Type; +var namedTypes = types.namedTypes; +var Node = namedTypes.Node; +var Expression = namedTypes.Expression; +var isArray = types.builtInTypes.array; +var hasOwn = Object.prototype.hasOwnProperty; +var b = types.builders; + +function Scope(path, parentScope) { + if (!(this instanceof Scope)) { + throw new Error("Scope constructor cannot be invoked without 'new'"); + } + if (!(path instanceof require("./node-path"))) { + throw new Error(""); + } + ScopeType.assert(path.value); + + var depth; + + if (parentScope) { + if (!(parentScope instanceof Scope)) { + throw new Error(""); + } + depth = parentScope.depth + 1; + } else { + parentScope = null; + depth = 0; + } + + Object.defineProperties(this, { + path: { value: path }, + node: { value: path.value }, + isGlobal: { value: !parentScope, enumerable: true }, + depth: { value: depth }, + parent: { value: parentScope }, + bindings: { value: {} } + }); +} + +var scopeTypes = [ + // Program nodes introduce global scopes. + namedTypes.Program, + + // Function is the supertype of FunctionExpression, + // FunctionDeclaration, ArrowExpression, etc. + namedTypes.Function, + + // In case you didn't know, the caught parameter shadows any variable + // of the same name in an outer scope. + namedTypes.CatchClause +]; + +var ScopeType = Type.or.apply(Type, scopeTypes); + +Scope.isEstablishedBy = function(node) { + return ScopeType.check(node); +}; + +var Sp = Scope.prototype; + +// Will be overridden after an instance lazily calls scanScope. +Sp.didScan = false; + +Sp.declares = function(name) { + this.scan(); + return hasOwn.call(this.bindings, name); +}; + +Sp.declareTemporary = function(prefix) { + if (prefix) { + if (!/^[a-z$_]/i.test(prefix)) { + throw new Error(""); + } + } else { + prefix = "t$"; + } + + // Include this.depth in the name to make sure the name does not + // collide with any variables in nested/enclosing scopes. + prefix += this.depth.toString(36) + "$"; + + this.scan(); + + var index = 0; + while (this.declares(prefix + index)) { + ++index; + } + + var name = prefix + index; + return this.bindings[name] = types.builders.identifier(name); +}; + +Sp.injectTemporary = function(identifier, init) { + identifier || (identifier = this.declareTemporary()); + + var bodyPath = this.path.get("body"); + if (namedTypes.BlockStatement.check(bodyPath.value)) { + bodyPath = bodyPath.get("body"); + } + + bodyPath.unshift( + b.variableDeclaration( + "var", + [b.variableDeclarator(identifier, init || null)] + ) + ); + + return identifier; +}; + +Sp.scan = function(force) { + if (force || !this.didScan) { + for (var name in this.bindings) { + // Empty out this.bindings, just in cases. + delete this.bindings[name]; + } + scanScope(this.path, this.bindings); + this.didScan = true; + } +}; + +Sp.getBindings = function () { + this.scan(); + return this.bindings; +}; + +function scanScope(path, bindings) { + var node = path.value; + ScopeType.assert(node); + + if (namedTypes.CatchClause.check(node)) { + // A catch clause establishes a new scope but the only variable + // bound in that scope is the catch parameter. Any other + // declarations create bindings in the outer scope. + addPattern(path.get("param"), bindings); + + } else { + recursiveScanScope(path, bindings); + } +} + +function recursiveScanScope(path, bindings) { + var node = path.value; + + if (path.parent && + namedTypes.FunctionExpression.check(path.parent.node) && + path.parent.node.id) { + addPattern(path.parent.get("id"), bindings); + } + + if (!node) { + // None of the remaining cases matter if node is falsy. + + } else if (isArray.check(node)) { + path.each(function(childPath) { + recursiveScanChild(childPath, bindings); + }); + + } else if (namedTypes.Function.check(node)) { + path.get("params").each(function(paramPath) { + addPattern(paramPath, bindings); + }); + + recursiveScanChild(path.get("body"), bindings); + + } else if (namedTypes.VariableDeclarator.check(node)) { + addPattern(path.get("id"), bindings); + recursiveScanChild(path.get("init"), bindings); + + } else if (node.type === "ImportSpecifier" || + node.type === "ImportNamespaceSpecifier" || + node.type === "ImportDefaultSpecifier") { + addPattern( + // Esprima used to use the .name field to refer to the local + // binding identifier for ImportSpecifier nodes, but .id for + // ImportNamespaceSpecifier and ImportDefaultSpecifier nodes. + // ESTree/Acorn/ESpree use .local for all three node types. + path.get(node.local ? "local" : + node.name ? "name" : "id"), + bindings + ); + + } else if (Node.check(node) && !Expression.check(node)) { + types.eachField(node, function(name, child) { + var childPath = path.get(name); + if (childPath.value !== child) { + throw new Error(""); + } + recursiveScanChild(childPath, bindings); + }); + } +} + +function recursiveScanChild(path, bindings) { + var node = path.value; + + if (!node || Expression.check(node)) { + // Ignore falsy values and Expressions. + + } else if (namedTypes.FunctionDeclaration.check(node)) { + addPattern(path.get("id"), bindings); + + } else if (namedTypes.ClassDeclaration && + namedTypes.ClassDeclaration.check(node)) { + addPattern(path.get("id"), bindings); + + } else if (ScopeType.check(node)) { + if (namedTypes.CatchClause.check(node)) { + var catchParamName = node.param.name; + var hadBinding = hasOwn.call(bindings, catchParamName); + + // Any declarations that occur inside the catch body that do + // not have the same name as the catch parameter should count + // as bindings in the outer scope. + recursiveScanScope(path.get("body"), bindings); + + // If a new binding matching the catch parameter name was + // created while scanning the catch body, ignore it because it + // actually refers to the catch parameter and not the outer + // scope that we're currently scanning. + if (!hadBinding) { + delete bindings[catchParamName]; + } + } + + } else { + recursiveScanScope(path, bindings); + } +} + +function addPattern(patternPath, bindings) { + var pattern = patternPath.value; + namedTypes.Pattern.assert(pattern); + + if (namedTypes.Identifier.check(pattern)) { + if (hasOwn.call(bindings, pattern.name)) { + bindings[pattern.name].push(patternPath); + } else { + bindings[pattern.name] = [patternPath]; + } + + } else if (namedTypes.ObjectPattern && + namedTypes.ObjectPattern.check(pattern)) { + patternPath.get('properties').each(function(propertyPath) { + var property = propertyPath.value; + if (namedTypes.Pattern.check(property)) { + addPattern(propertyPath, bindings); + } else if (namedTypes.Property.check(property)) { + addPattern(propertyPath.get('value'), bindings); + } else if (namedTypes.SpreadProperty && + namedTypes.SpreadProperty.check(property)) { + addPattern(propertyPath.get('argument'), bindings); + } + }); + + } else if (namedTypes.ArrayPattern && + namedTypes.ArrayPattern.check(pattern)) { + patternPath.get('elements').each(function(elementPath) { + var element = elementPath.value; + if (namedTypes.Pattern.check(element)) { + addPattern(elementPath, bindings); + } else if (namedTypes.SpreadElement && + namedTypes.SpreadElement.check(element)) { + addPattern(elementPath.get("argument"), bindings); + } + }); + + } else if (namedTypes.PropertyPattern && + namedTypes.PropertyPattern.check(pattern)) { + addPattern(patternPath.get('pattern'), bindings); + + } else if ((namedTypes.SpreadElementPattern && + namedTypes.SpreadElementPattern.check(pattern)) || + (namedTypes.SpreadPropertyPattern && + namedTypes.SpreadPropertyPattern.check(pattern))) { + addPattern(patternPath.get('argument'), bindings); + } +} + +Sp.lookup = function(name) { + for (var scope = this; scope; scope = scope.parent) + if (scope.declares(name)) + break; + return scope; +}; + +Sp.getGlobalScope = function() { + var scope = this; + while (!scope.isGlobal) + scope = scope.parent; + return scope; +}; + +module.exports = Scope; diff --git a/lib/shared.js b/lib/shared.js new file mode 100644 index 0000000..3e84086 --- /dev/null +++ b/lib/shared.js @@ -0,0 +1,41 @@ +var types = require("../lib/types"); +var Type = types.Type; +var builtin = types.builtInTypes; +var isNumber = builtin.number; + +// An example of constructing a new type with arbitrary constraints from +// an existing type. +exports.geq = function(than) { + return new Type(function(value) { + return isNumber.check(value) && value >= than; + }, isNumber + " >= " + than); +}; + +// Default value-returning functions that may optionally be passed as a +// third argument to Def.prototype.field. +exports.defaults = { + // Functions were used because (among other reasons) that's the most + // elegant way to allow for the emptyArray one always to give a new + // array instance. + "null": function() { return null }, + "emptyArray": function() { return [] }, + "false": function() { return false }, + "true": function() { return true }, + "undefined": function() {} +}; + +var naiveIsPrimitive = Type.or( + builtin.string, + builtin.number, + builtin.boolean, + builtin.null, + builtin.undefined +); + +exports.isPrimitive = new Type(function(value) { + if (value === null) + return true; + var type = typeof value; + return !(type === "object" || + type === "function"); +}, naiveIsPrimitive.toString()); diff --git a/lib/types.js b/lib/types.js new file mode 100644 index 0000000..b4d4aee --- /dev/null +++ b/lib/types.js @@ -0,0 +1,828 @@ +var Ap = Array.prototype; +var slice = Ap.slice; +var map = Ap.map; +var each = Ap.forEach; +var Op = Object.prototype; +var objToStr = Op.toString; +var funObjStr = objToStr.call(function(){}); +var strObjStr = objToStr.call(""); +var hasOwn = Op.hasOwnProperty; + +// A type is an object with a .check method that takes a value and returns +// true or false according to whether the value matches the type. + +function Type(check, name) { + var self = this; + if (!(self instanceof Type)) { + throw new Error("Type constructor cannot be invoked without 'new'"); + } + + // Unfortunately we can't elegantly reuse isFunction and isString, + // here, because this code is executed while defining those types. + if (objToStr.call(check) !== funObjStr) { + throw new Error(check + " is not a function"); + } + + // The `name` parameter can be either a function or a string. + var nameObjStr = objToStr.call(name); + if (!(nameObjStr === funObjStr || + nameObjStr === strObjStr)) { + throw new Error(name + " is neither a function nor a string"); + } + + Object.defineProperties(self, { + name: { value: name }, + check: { + value: function(value, deep) { + var result = check.call(self, value, deep); + if (!result && deep && objToStr.call(deep) === funObjStr) + deep(self, value); + return result; + } + } + }); +} + +var Tp = Type.prototype; + +// Throughout this file we use Object.defineProperty to prevent +// redefinition of exported properties. +exports.Type = Type; + +// Like .check, except that failure triggers an AssertionError. +Tp.assert = function(value, deep) { + if (!this.check(value, deep)) { + var str = shallowStringify(value); + throw new Error(str + " does not match type " + this); + } + return true; +}; + +function shallowStringify(value) { + if (isObject.check(value)) + return "{" + Object.keys(value).map(function(key) { + return key + ": " + value[key]; + }).join(", ") + "}"; + + if (isArray.check(value)) + return "[" + value.map(shallowStringify).join(", ") + "]"; + + return JSON.stringify(value); +} + +Tp.toString = function() { + var name = this.name; + + if (isString.check(name)) + return name; + + if (isFunction.check(name)) + return name.call(this) + ""; + + return name + " type"; +}; + +var builtInCtorFns = []; +var builtInCtorTypes = []; +var builtInTypes = {}; +exports.builtInTypes = builtInTypes; + +function defBuiltInType(example, name) { + var objStr = objToStr.call(example); + + var type = new Type(function(value) { + return objToStr.call(value) === objStr; + }, name); + + builtInTypes[name] = type; + + if (example && typeof example.constructor === "function") { + builtInCtorFns.push(example.constructor); + builtInCtorTypes.push(type); + } + + return type; +} + +// These types check the underlying [[Class]] attribute of the given +// value, rather than using the problematic typeof operator. Note however +// that no subtyping is considered; so, for instance, isObject.check +// returns false for [], /./, new Date, and null. +var isString = defBuiltInType("truthy", "string"); +var isFunction = defBuiltInType(function(){}, "function"); +var isArray = defBuiltInType([], "array"); +var isObject = defBuiltInType({}, "object"); +var isRegExp = defBuiltInType(/./, "RegExp"); +var isDate = defBuiltInType(new Date, "Date"); +var isNumber = defBuiltInType(3, "number"); +var isBoolean = defBuiltInType(true, "boolean"); +var isNull = defBuiltInType(null, "null"); +var isUndefined = defBuiltInType(void 0, "undefined"); + +// There are a number of idiomatic ways of expressing types, so this +// function serves to coerce them all to actual Type objects. Note that +// providing the name argument is not necessary in most cases. +function toType(from, name) { + // The toType function should of course be idempotent. + if (from instanceof Type) + return from; + + // The Def type is used as a helper for constructing compound + // interface types for AST nodes. + if (from instanceof Def) + return from.type; + + // Support [ElemType] syntax. + if (isArray.check(from)) + return Type.fromArray(from); + + // Support { someField: FieldType, ... } syntax. + if (isObject.check(from)) + return Type.fromObject(from); + + if (isFunction.check(from)) { + var bicfIndex = builtInCtorFns.indexOf(from); + if (bicfIndex >= 0) { + return builtInCtorTypes[bicfIndex]; + } + + // If isFunction.check(from), and from is not a built-in + // constructor, assume from is a binary predicate function we can + // use to define the type. + return new Type(from, name); + } + + // As a last resort, toType returns a type that matches any value that + // is === from. This is primarily useful for literal values like + // toType(null), but it has the additional advantage of allowing + // toType to be a total function. + return new Type(function(value) { + return value === from; + }, isUndefined.check(name) ? function() { + return from + ""; + } : name); +} + +// Returns a type that matches the given value iff any of type1, type2, +// etc. match the value. +Type.or = function(/* type1, type2, ... */) { + var types = []; + var len = arguments.length; + for (var i = 0; i < len; ++i) + types.push(toType(arguments[i])); + + return new Type(function(value, deep) { + for (var i = 0; i < len; ++i) + if (types[i].check(value, deep)) + return true; + return false; + }, function() { + return types.join(" | "); + }); +}; + +Type.fromArray = function(arr) { + if (!isArray.check(arr)) { + throw new Error(""); + } + if (arr.length !== 1) { + throw new Error("only one element type is permitted for typed arrays"); + } + return toType(arr[0]).arrayOf(); +}; + +Tp.arrayOf = function() { + var elemType = this; + return new Type(function(value, deep) { + return isArray.check(value) && value.every(function(elem) { + return elemType.check(elem, deep); + }); + }, function() { + return "[" + elemType + "]"; + }); +}; + +Type.fromObject = function(obj) { + var fields = Object.keys(obj).map(function(name) { + return new Field(name, obj[name]); + }); + + return new Type(function(value, deep) { + return isObject.check(value) && fields.every(function(field) { + return field.type.check(value[field.name], deep); + }); + }, function() { + return "{ " + fields.join(", ") + " }"; + }); +}; + +function Field(name, type, defaultFn, hidden) { + var self = this; + + if (!(self instanceof Field)) { + throw new Error("Field constructor cannot be invoked without 'new'"); + } + isString.assert(name); + + type = toType(type); + + var properties = { + name: { value: name }, + type: { value: type }, + hidden: { value: !!hidden } + }; + + if (isFunction.check(defaultFn)) { + properties.defaultFn = { value: defaultFn }; + } + + Object.defineProperties(self, properties); +} + +var Fp = Field.prototype; + +Fp.toString = function() { + return JSON.stringify(this.name) + ": " + this.type; +}; + +Fp.getValue = function(obj) { + var value = obj[this.name]; + + if (!isUndefined.check(value)) + return value; + + if (this.defaultFn) + value = this.defaultFn.call(obj); + + return value; +}; + +// Define a type whose name is registered in a namespace (the defCache) so +// that future definitions will return the same type given the same name. +// In particular, this system allows for circular and forward definitions. +// The Def object d returned from Type.def may be used to configure the +// type d.type by calling methods such as d.bases, d.build, and d.field. +Type.def = function(typeName) { + isString.assert(typeName); + return hasOwn.call(defCache, typeName) + ? defCache[typeName] + : defCache[typeName] = new Def(typeName); +}; + +// In order to return the same Def instance every time Type.def is called +// with a particular name, those instances need to be stored in a cache. +var defCache = Object.create(null); + +function Def(typeName) { + var self = this; + if (!(self instanceof Def)) { + throw new Error("Def constructor cannot be invoked without 'new'"); + } + + Object.defineProperties(self, { + typeName: { value: typeName }, + baseNames: { value: [] }, + ownFields: { value: Object.create(null) }, + + // These two are populated during finalization. + allSupertypes: { value: Object.create(null) }, // Includes own typeName. + supertypeList: { value: [] }, // Linear inheritance hierarchy. + allFields: { value: Object.create(null) }, // Includes inherited fields. + fieldNames: { value: [] }, // Non-hidden keys of allFields. + + type: { + value: new Type(function(value, deep) { + return self.check(value, deep); + }, typeName) + } + }); +} + +Def.fromValue = function(value) { + if (value && typeof value === "object") { + var type = value.type; + if (typeof type === "string" && + hasOwn.call(defCache, type)) { + var d = defCache[type]; + if (d.finalized) { + return d; + } + } + } + + return null; +}; + +var Dp = Def.prototype; + +Dp.isSupertypeOf = function(that) { + if (that instanceof Def) { + if (this.finalized !== true || + that.finalized !== true) { + throw new Error(""); + } + return hasOwn.call(that.allSupertypes, this.typeName); + } else { + throw new Error(that + " is not a Def"); + } +}; + +// Note that the list returned by this function is a copy of the internal +// supertypeList, *without* the typeName itself as the first element. +exports.getSupertypeNames = function(typeName) { + if (!hasOwn.call(defCache, typeName)) { + throw new Error(""); + } + var d = defCache[typeName]; + if (d.finalized !== true) { + throw new Error(""); + } + return d.supertypeList.slice(1); +}; + +// Returns an object mapping from every known type in the defCache to the +// most specific supertype whose name is an own property of the candidates +// object. +exports.computeSupertypeLookupTable = function(candidates) { + var table = {}; + var typeNames = Object.keys(defCache); + var typeNameCount = typeNames.length; + + for (var i = 0; i < typeNameCount; ++i) { + var typeName = typeNames[i]; + var d = defCache[typeName]; + if (d.finalized !== true) { + throw new Error("" + typeName); + } + for (var j = 0; j < d.supertypeList.length; ++j) { + var superTypeName = d.supertypeList[j]; + if (hasOwn.call(candidates, superTypeName)) { + table[typeName] = superTypeName; + break; + } + } + } + + return table; +}; + +Dp.checkAllFields = function(value, deep) { + var allFields = this.allFields; + if (this.finalized !== true) { + throw new Error("" + this.typeName); + } + + function checkFieldByName(name) { + var field = allFields[name]; + var type = field.type; + var child = field.getValue(value); + return type.check(child, deep); + } + + return isObject.check(value) + && Object.keys(allFields).every(checkFieldByName); +}; + +Dp.check = function(value, deep) { + if (this.finalized !== true) { + throw new Error( + "prematurely checking unfinalized type " + this.typeName + ); + } + + // A Def type can only match an object value. + if (!isObject.check(value)) + return false; + + var vDef = Def.fromValue(value); + if (!vDef) { + // If we couldn't infer the Def associated with the given value, + // and we expected it to be a SourceLocation or a Position, it was + // probably just missing a "type" field (because Esprima does not + // assign a type property to such nodes). Be optimistic and let + // this.checkAllFields make the final decision. + if (this.typeName === "SourceLocation" || + this.typeName === "Position") { + return this.checkAllFields(value, deep); + } + + // Calling this.checkAllFields for any other type of node is both + // bad for performance and way too forgiving. + return false; + } + + // If checking deeply and vDef === this, then we only need to call + // checkAllFields once. Calling checkAllFields is too strict when deep + // is false, because then we only care about this.isSupertypeOf(vDef). + if (deep && vDef === this) + return this.checkAllFields(value, deep); + + // In most cases we rely exclusively on isSupertypeOf to make O(1) + // subtyping determinations. This suffices in most situations outside + // of unit tests, since interface conformance is checked whenever new + // instances are created using builder functions. + if (!this.isSupertypeOf(vDef)) + return false; + + // The exception is when deep is true; then, we recursively check all + // fields. + if (!deep) + return true; + + // Use the more specific Def (vDef) to perform the deep check, but + // shallow-check fields defined by the less specific Def (this). + return vDef.checkAllFields(value, deep) + && this.checkAllFields(value, false); +}; + +Dp.bases = function() { + var args = slice.call(arguments); + var bases = this.baseNames; + + if (this.finalized) { + if (args.length !== bases.length) { + throw new Error(""); + } + for (var i = 0; i < args.length; i++) { + if (args[i] !== bases[i]) { + throw new Error(""); + } + } + return this; + } + + args.forEach(function(baseName) { + isString.assert(baseName); + + // This indexOf lookup may be O(n), but the typical number of base + // names is very small, and indexOf is a native Array method. + if (bases.indexOf(baseName) < 0) + bases.push(baseName); + }); + + return this; // For chaining. +}; + +// False by default until .build(...) is called on an instance. +Object.defineProperty(Dp, "buildable", { value: false }); + +var builders = {}; +exports.builders = builders; + +// This object is used as prototype for any node created by a builder. +var nodePrototype = {}; + +// Call this function to define a new method to be shared by all AST +// nodes. The replaced method (if any) is returned for easy wrapping. +exports.defineMethod = function(name, func) { + var old = nodePrototype[name]; + + // Pass undefined as func to delete nodePrototype[name]. + if (isUndefined.check(func)) { + delete nodePrototype[name]; + + } else { + isFunction.assert(func); + + Object.defineProperty(nodePrototype, name, { + enumerable: true, // For discoverability. + configurable: true, // For delete proto[name]. + value: func + }); + } + + return old; +}; + +var isArrayOfString = isString.arrayOf(); + +// Calling the .build method of a Def simultaneously marks the type as +// buildable (by defining builders[getBuilderName(typeName)]) and +// specifies the order of arguments that should be passed to the builder +// function to create an instance of the type. +Dp.build = function(/* param1, param2, ... */) { + var self = this; + + var newBuildParams = slice.call(arguments); + isArrayOfString.assert(newBuildParams); + + // Calling Def.prototype.build multiple times has the effect of merely + // redefining this property. + Object.defineProperty(self, "buildParams", { + value: newBuildParams, + writable: false, + enumerable: false, + configurable: true + }); + + if (self.buildable) { + // If this Def is already buildable, update self.buildParams and + // continue using the old builder function. + return self; + } + + // Every buildable type will have its "type" field filled in + // automatically. This includes types that are not subtypes of Node, + // like SourceLocation, but that seems harmless (TODO?). + self.field("type", String, function() { return self.typeName }); + + // Override Dp.buildable for this Def instance. + Object.defineProperty(self, "buildable", { value: true }); + + Object.defineProperty(builders, getBuilderName(self.typeName), { + enumerable: true, + + value: function() { + var args = arguments; + var argc = args.length; + var built = Object.create(nodePrototype); + + if (!self.finalized) { + throw new Error( + "attempting to instantiate unfinalized type " + + self.typeName + ); + } + + function add(param, i) { + if (hasOwn.call(built, param)) + return; + + var all = self.allFields; + if (!hasOwn.call(all, param)) { + throw new Error("" + param); + } + + var field = all[param]; + var type = field.type; + var value; + + if (isNumber.check(i) && i < argc) { + value = args[i]; + } else if (field.defaultFn) { + // Expose the partially-built object to the default + // function as its `this` object. + value = field.defaultFn.call(built); + } else { + var message = "no value or default function given for field " + + JSON.stringify(param) + " of " + self.typeName + "(" + + self.buildParams.map(function(name) { + return all[name]; + }).join(", ") + ")"; + throw new Error(message); + } + + if (!type.check(value)) { + throw new Error( + shallowStringify(value) + + " does not match field " + field + + " of type " + self.typeName + ); + } + + // TODO Could attach getters and setters here to enforce + // dynamic type safety. + built[param] = value; + } + + self.buildParams.forEach(function(param, i) { + add(param, i); + }); + + Object.keys(self.allFields).forEach(function(param) { + add(param); // Use the default value. + }); + + // Make sure that the "type" field was filled automatically. + if (built.type !== self.typeName) { + throw new Error(""); + } + + return built; + } + }); + + return self; // For chaining. +}; + +function getBuilderName(typeName) { + return typeName.replace(/^[A-Z]+/, function(upperCasePrefix) { + var len = upperCasePrefix.length; + switch (len) { + case 0: return ""; + // If there's only one initial capital letter, just lower-case it. + case 1: return upperCasePrefix.toLowerCase(); + default: + // If there's more than one initial capital letter, lower-case + // all but the last one, so that XMLDefaultDeclaration (for + // example) becomes xmlDefaultDeclaration. + return upperCasePrefix.slice( + 0, len - 1).toLowerCase() + + upperCasePrefix.charAt(len - 1); + } + }); +} +exports.getBuilderName = getBuilderName; + +function getStatementBuilderName(typeName) { + typeName = getBuilderName(typeName); + return typeName.replace(/(Expression)?$/, "Statement"); +} +exports.getStatementBuilderName = getStatementBuilderName; + +// The reason fields are specified using .field(...) instead of an object +// literal syntax is somewhat subtle: the object literal syntax would +// support only one key and one value, but with .field(...) we can pass +// any number of arguments to specify the field. +Dp.field = function(name, type, defaultFn, hidden) { + if (this.finalized) { + console.error("Ignoring attempt to redefine field " + + JSON.stringify(name) + " of finalized type " + + JSON.stringify(this.typeName)); + return this; + } + this.ownFields[name] = new Field(name, type, defaultFn, hidden); + return this; // For chaining. +}; + +var namedTypes = {}; +exports.namedTypes = namedTypes; + +// Like Object.keys, but aware of what fields each AST type should have. +function getFieldNames(object) { + var d = Def.fromValue(object); + if (d) { + return d.fieldNames.slice(0); + } + + if ("type" in object) { + throw new Error( + "did not recognize object of type " + + JSON.stringify(object.type) + ); + } + + return Object.keys(object); +} +exports.getFieldNames = getFieldNames; + +// Get the value of an object property, taking object.type and default +// functions into account. +function getFieldValue(object, fieldName) { + var d = Def.fromValue(object); + if (d) { + var field = d.allFields[fieldName]; + if (field) { + return field.getValue(object); + } + } + + return object[fieldName]; +} +exports.getFieldValue = getFieldValue; + +// Iterate over all defined fields of an object, including those missing +// or undefined, passing each field name and effective value (as returned +// by getFieldValue) to the callback. If the object has no corresponding +// Def, the callback will never be called. +exports.eachField = function(object, callback, context) { + getFieldNames(object).forEach(function(name) { + callback.call(this, name, getFieldValue(object, name)); + }, context); +}; + +// Similar to eachField, except that iteration stops as soon as the +// callback returns a truthy value. Like Array.prototype.some, the final +// result is either true or false to indicates whether the callback +// returned true for any element or not. +exports.someField = function(object, callback, context) { + return getFieldNames(object).some(function(name) { + return callback.call(this, name, getFieldValue(object, name)); + }, context); +}; + +// This property will be overridden as true by individual Def instances +// when they are finalized. +Object.defineProperty(Dp, "finalized", { value: false }); + +Dp.finalize = function() { + var self = this; + + // It's not an error to finalize a type more than once, but only the + // first call to .finalize does anything. + if (!self.finalized) { + var allFields = self.allFields; + var allSupertypes = self.allSupertypes; + + self.baseNames.forEach(function(name) { + var def = defCache[name]; + if (def instanceof Def) { + def.finalize(); + extend(allFields, def.allFields); + extend(allSupertypes, def.allSupertypes); + } else { + var message = "unknown supertype name " + + JSON.stringify(name) + + " for subtype " + + JSON.stringify(self.typeName); + throw new Error(message); + } + }); + + // TODO Warn if fields are overridden with incompatible types. + extend(allFields, self.ownFields); + allSupertypes[self.typeName] = self; + + self.fieldNames.length = 0; + for (var fieldName in allFields) { + if (hasOwn.call(allFields, fieldName) && + !allFields[fieldName].hidden) { + self.fieldNames.push(fieldName); + } + } + + // Types are exported only once they have been finalized. + Object.defineProperty(namedTypes, self.typeName, { + enumerable: true, + value: self.type + }); + + Object.defineProperty(self, "finalized", { value: true }); + + // A linearization of the inheritance hierarchy. + populateSupertypeList(self.typeName, self.supertypeList); + + if (self.buildable && self.supertypeList.lastIndexOf("Expression") >= 0) { + wrapExpressionBuilderWithStatement(self.typeName); + } + } +}; + +// Adds an additional builder for Expression subtypes +// that wraps the built Expression in an ExpressionStatements. +function wrapExpressionBuilderWithStatement(typeName) { + var wrapperName = getStatementBuilderName(typeName); + + // skip if the builder already exists + if (builders[wrapperName]) return; + + // the builder function to wrap with builders.ExpressionStatement + var wrapped = builders[getBuilderName(typeName)]; + + // skip if there is nothing to wrap + if (!wrapped) return; + + builders[wrapperName] = function() { + return builders.expressionStatement(wrapped.apply(builders, arguments)); + }; +} + +function populateSupertypeList(typeName, list) { + list.length = 0; + list.push(typeName); + + var lastSeen = Object.create(null); + + for (var pos = 0; pos < list.length; ++pos) { + typeName = list[pos]; + var d = defCache[typeName]; + if (d.finalized !== true) { + throw new Error(""); + } + + // If we saw typeName earlier in the breadth-first traversal, + // delete the last-seen occurrence. + if (hasOwn.call(lastSeen, typeName)) { + delete list[lastSeen[typeName]]; + } + + // Record the new index of the last-seen occurrence of typeName. + lastSeen[typeName] = pos; + + // Enqueue the base names of this type. + list.push.apply(list, d.baseNames); + } + + // Compaction loop to remove array holes. + for (var to = 0, from = to, len = list.length; from < len; ++from) { + if (hasOwn.call(list, from)) { + list[to++] = list[from]; + } + } + + list.length = to; +} + +function extend(into, from) { + Object.keys(from).forEach(function(name) { + into[name] = from[name]; + }); + + return into; +}; + +exports.finalize = function() { + Object.keys(defCache).forEach(function(name) { + defCache[name].finalize(); + }); +}; diff --git a/main.js b/main.js new file mode 100644 index 0000000..374ae4f --- /dev/null +++ b/main.js @@ -0,0 +1,33 @@ +var types = require("./lib/types"); + +// This core module of AST types captures ES5 as it is parsed today by +// git://github.com/ariya/esprima.git#master. +require("./def/core"); + +// Feel free to add to or remove from this list of extension modules to +// configure the precise type hierarchy that you need. +require("./def/es6"); +require("./def/es7"); +require("./def/mozilla"); +require("./def/e4x"); +require("./def/fb-harmony"); +require("./def/esprima"); +require("./def/babel"); + +types.finalize(); + +exports.Type = types.Type; +exports.builtInTypes = types.builtInTypes; +exports.namedTypes = types.namedTypes; +exports.builders = types.builders; +exports.defineMethod = types.defineMethod; +exports.getFieldNames = types.getFieldNames; +exports.getFieldValue = types.getFieldValue; +exports.eachField = types.eachField; +exports.someField = types.someField; +exports.getSupertypeNames = types.getSupertypeNames; +exports.astNodesAreEquivalent = require("./lib/equiv"); +exports.finalize = types.finalize; +exports.NodePath = require("./lib/node-path"); +exports.PathVisitor = require("./lib/path-visitor"); +exports.visit = exports.PathVisitor.visit; diff --git a/package.json b/package.json new file mode 100644 index 0000000..ce3b256 --- /dev/null +++ b/package.json @@ -0,0 +1,42 @@ +{ + "author": "Ben Newman ", + "name": "ast-types", + "description": "Esprima-compatible implementation of the Mozilla JS Parser API", + "keywords": [ + "ast", + "abstract syntax tree", + "hierarchy", + "mozilla", + "spidermonkey", + "parser api", + "esprima", + "types", + "type system", + "type checking", + "dynamic types", + "parsing", + "transformation", + "syntax" + ], + "version": "0.8.13", + "homepage": "http://github.com/benjamn/ast-types", + "repository": { + "type": "git", + "url": "git://github.com/benjamn/ast-types.git" + }, + "license": "MIT", + "main": "main.js", + "scripts": { + "test": "mocha --reporter spec --full-trace test/run.js" + }, + "dependencies": {}, + "devDependencies": { + "babel-core": "^5.6.15", + "esprima": "~1.2.2", + "esprima-fb": "~14001.1.0-dev-harmony-fb", + "mocha": "~2.2.5" + }, + "engines": { + "node": ">= 0.8" + } +} diff --git a/test/data/backbone.js b/test/data/backbone.js new file mode 100644 index 0000000..13f60ae --- /dev/null +++ b/test/data/backbone.js @@ -0,0 +1,1572 @@ +// Backbone.js 1.0.0 + +// (c) 2010-2013 Jeremy Ashkenas, DocumentCloud Inc. +// (c) 2011-2013 Jeremy Ashkenas, DocumentCloud and Investigative Reporters & Editors +// Backbone may be freely distributed under the MIT license. +// For all details and documentation: +// http://backbonejs.org + +(function(){ + + // Initial Setup + // ------------- + + // Save a reference to the global object (`window` in the browser, `exports` + // on the server). + var root = this; + + // Save the previous value of the `Backbone` variable, so that it can be + // restored later on, if `noConflict` is used. + var previousBackbone = root.Backbone; + + // Create local references to array methods we'll want to use later. + var array = []; + var push = array.push; + var slice = array.slice; + var splice = array.splice; + + // The top-level namespace. All public Backbone classes and modules will + // be attached to this. Exported for both the browser and the server. + var Backbone; + if (typeof exports !== 'undefined') { + Backbone = exports; + } else { + Backbone = root.Backbone = {}; + } + + // Current version of the library. Keep in sync with `package.json`. + Backbone.VERSION = '1.0.0'; + + // Require Underscore, if we're on the server, and it's not already present. + var _ = root._; + if (!_ && (typeof require !== 'undefined')) _ = require('underscore'); + + // For Backbone's purposes, jQuery, Zepto, Ender, or My Library (kidding) owns + // the `$` variable. + Backbone.$ = root.jQuery || root.Zepto || root.ender || root.$; + + // Runs Backbone.js in *noConflict* mode, returning the `Backbone` variable + // to its previous owner. Returns a reference to this Backbone object. + Backbone.noConflict = function() { + root.Backbone = previousBackbone; + return this; + }; + + // Turn on `emulateHTTP` to support legacy HTTP servers. Setting this option + // will fake `"PUT"` and `"DELETE"` requests via the `_method` parameter and + // set a `X-Http-Method-Override` header. + Backbone.emulateHTTP = false; + + // Turn on `emulateJSON` to support legacy servers that can't deal with direct + // `application/json` requests ... will encode the body as + // `application/x-www-form-urlencoded` instead and will send the model in a + // form param named `model`. + Backbone.emulateJSON = false; + + // Backbone.Events + // --------------- + + // A module that can be mixed in to *any object* in order to provide it with + // custom events. You may bind with `on` or remove with `off` callback + // functions to an event; `trigger`-ing an event fires all callbacks in + // succession. + // + // var object = {}; + // _.extend(object, Backbone.Events); + // object.on('expand', function(){ alert('expanded'); }); + // object.trigger('expand'); + // + var Events = Backbone.Events = { + + // Bind an event to a `callback` function. Passing `"all"` will bind + // the callback to all events fired. + on: function(name, callback, context) { + if (!eventsApi(this, 'on', name, [callback, context]) || !callback) return this; + this._events || (this._events = {}); + var events = this._events[name] || (this._events[name] = []); + events.push({callback: callback, context: context, ctx: context || this}); + return this; + }, + + // Bind an event to only be triggered a single time. After the first time + // the callback is invoked, it will be removed. + once: function(name, callback, context) { + if (!eventsApi(this, 'once', name, [callback, context]) || !callback) return this; + var self = this; + var once = _.once(function() { + self.off(name, once); + callback.apply(this, arguments); + }); + once._callback = callback; + return this.on(name, once, context); + }, + + // Remove one or many callbacks. If `context` is null, removes all + // callbacks with that function. If `callback` is null, removes all + // callbacks for the event. If `name` is null, removes all bound + // callbacks for all events. + off: function(name, callback, context) { + var retain, ev, events, names, i, l, j, k; + if (!this._events || !eventsApi(this, 'off', name, [callback, context])) return this; + if (!name && !callback && !context) { + this._events = {}; + return this; + } + + names = name ? [name] : _.keys(this._events); + for (i = 0, l = names.length; i < l; i++) { + name = names[i]; + if (events = this._events[name]) { + this._events[name] = retain = []; + if (callback || context) { + for (j = 0, k = events.length; j < k; j++) { + ev = events[j]; + if ((callback && callback !== ev.callback && callback !== ev.callback._callback) || + (context && context !== ev.context)) { + retain.push(ev); + } + } + } + if (!retain.length) delete this._events[name]; + } + } + + return this; + }, + + // Trigger one or many events, firing all bound callbacks. Callbacks are + // passed the same arguments as `trigger` is, apart from the event name + // (unless you're listening on `"all"`, which will cause your callback to + // receive the true name of the event as the first argument). + trigger: function(name) { + if (!this._events) return this; + var args = slice.call(arguments, 1); + if (!eventsApi(this, 'trigger', name, args)) return this; + var events = this._events[name]; + var allEvents = this._events.all; + if (events) triggerEvents(events, args); + if (allEvents) triggerEvents(allEvents, arguments); + return this; + }, + + // Tell this object to stop listening to either specific events ... or + // to every object it's currently listening to. + stopListening: function(obj, name, callback) { + var listeners = this._listeners; + if (!listeners) return this; + var deleteListener = !name && !callback; + if (typeof name === 'object') callback = this; + if (obj) (listeners = {})[obj._listenerId] = obj; + for (var id in listeners) { + listeners[id].off(name, callback, this); + if (deleteListener) delete this._listeners[id]; + } + return this; + } + + }; + + // Regular expression used to split event strings. + var eventSplitter = /\s+/; + + // Implement fancy features of the Events API such as multiple event + // names `"change blur"` and jQuery-style event maps `{change: action}` + // in terms of the existing API. + var eventsApi = function(obj, action, name, rest) { + if (!name) return true; + + // Handle event maps. + if (typeof name === 'object') { + for (var key in name) { + obj[action].apply(obj, [key, name[key]].concat(rest)); + } + return false; + } + + // Handle space separated event names. + if (eventSplitter.test(name)) { + var names = name.split(eventSplitter); + for (var i = 0, l = names.length; i < l; i++) { + obj[action].apply(obj, [names[i]].concat(rest)); + } + return false; + } + + return true; + }; + + // A difficult-to-believe, but optimized internal dispatch function for + // triggering events. Tries to keep the usual cases speedy (most internal + // Backbone events have 3 arguments). + var triggerEvents = function(events, args) { + var ev, i = -1, l = events.length, a1 = args[0], a2 = args[1], a3 = args[2]; + switch (args.length) { + case 0: while (++i < l) (ev = events[i]).callback.call(ev.ctx); return; + case 1: while (++i < l) (ev = events[i]).callback.call(ev.ctx, a1); return; + case 2: while (++i < l) (ev = events[i]).callback.call(ev.ctx, a1, a2); return; + case 3: while (++i < l) (ev = events[i]).callback.call(ev.ctx, a1, a2, a3); return; + default: while (++i < l) (ev = events[i]).callback.apply(ev.ctx, args); + } + }; + + var listenMethods = {listenTo: 'on', listenToOnce: 'once'}; + + // Inversion-of-control versions of `on` and `once`. Tell *this* object to + // listen to an event in another object ... keeping track of what it's + // listening to. + _.each(listenMethods, function(implementation, method) { + Events[method] = function(obj, name, callback) { + var listeners = this._listeners || (this._listeners = {}); + var id = obj._listenerId || (obj._listenerId = _.uniqueId('l')); + listeners[id] = obj; + if (typeof name === 'object') callback = this; + obj[implementation](name, callback, this); + return this; + }; + }); + + // Aliases for backwards compatibility. + Events.bind = Events.on; + Events.unbind = Events.off; + + // Allow the `Backbone` object to serve as a global event bus, for folks who + // want global "pubsub" in a convenient place. + _.extend(Backbone, Events); + + // Backbone.Model + // -------------- + + // Backbone **Models** are the basic data object in the framework -- + // frequently representing a row in a table in a database on your server. + // A discrete chunk of data and a bunch of useful, related methods for + // performing computations and transformations on that data. + + // Create a new model with the specified attributes. A client id (`cid`) + // is automatically generated and assigned for you. + var Model = Backbone.Model = function(attributes, options) { + var defaults; + var attrs = attributes || {}; + options || (options = {}); + this.cid = _.uniqueId('c'); + this.attributes = {}; + if (options.collection) this.collection = options.collection; + if (options.parse) attrs = this.parse(attrs, options) || {}; + options._attrs = attrs; + if (defaults = _.result(this, 'defaults')) { + attrs = _.defaults({}, attrs, defaults); + } + this.set(attrs, options); + this.changed = {}; + this.initialize.apply(this, arguments); + }; + + // Attach all inheritable methods to the Model prototype. + _.extend(Model.prototype, Events, { + + // A hash of attributes whose current and previous value differ. + changed: null, + + // The value returned during the last failed validation. + validationError: null, + + // The default name for the JSON `id` attribute is `"id"`. MongoDB and + // CouchDB users may want to set this to `"_id"`. + idAttribute: 'id', + + // Initialize is an empty function by default. Override it with your own + // initialization logic. + initialize: function(){}, + + // Return a copy of the model's `attributes` object. + toJSON: function(options) { + return _.clone(this.attributes); + }, + + // Proxy `Backbone.sync` by default -- but override this if you need + // custom syncing semantics for *this* particular model. + sync: function() { + return Backbone.sync.apply(this, arguments); + }, + + // Get the value of an attribute. + get: function(attr) { + return this.attributes[attr]; + }, + + // Get the HTML-escaped value of an attribute. + escape: function(attr) { + return _.escape(this.get(attr)); + }, + + // Returns `true` if the attribute contains a value that is not null + // or undefined. + has: function(attr) { + return this.get(attr) != null; + }, + + // Set a hash of model attributes on the object, firing `"change"`. This is + // the core primitive operation of a model, updating the data and notifying + // anyone who needs to know about the change in state. The heart of the beast. + set: function(key, val, options) { + var attr, attrs, unset, changes, silent, changing, prev, current; + if (key == null) return this; + + // Handle both `"key", value` and `{key: value}` -style arguments. + if (typeof key === 'object') { + attrs = key; + options = val; + } else { + (attrs = {})[key] = val; + } + + options || (options = {}); + + // Run validation. + if (!this._validate(attrs, options)) return false; + + // Extract attributes and options. + unset = options.unset; + silent = options.silent; + changes = []; + changing = this._changing; + this._changing = true; + + if (!changing) { + this._previousAttributes = _.clone(this.attributes); + this.changed = {}; + } + current = this.attributes, prev = this._previousAttributes; + + // Check for changes of `id`. + if (this.idAttribute in attrs) this.id = attrs[this.idAttribute]; + + // For each `set` attribute, update or delete the current value. + for (attr in attrs) { + val = attrs[attr]; + if (!_.isEqual(current[attr], val)) changes.push(attr); + if (!_.isEqual(prev[attr], val)) { + this.changed[attr] = val; + } else { + delete this.changed[attr]; + } + unset ? delete current[attr] : current[attr] = val; + } + + // Trigger all relevant attribute changes. + if (!silent) { + if (changes.length) this._pending = true; + for (var i = 0, l = changes.length; i < l; i++) { + this.trigger('change:' + changes[i], this, current[changes[i]], options); + } + } + + // You might be wondering why there's a `while` loop here. Changes can + // be recursively nested within `"change"` events. + if (changing) return this; + if (!silent) { + while (this._pending) { + this._pending = false; + this.trigger('change', this, options); + } + } + this._pending = false; + this._changing = false; + return this; + }, + + // Remove an attribute from the model, firing `"change"`. `unset` is a noop + // if the attribute doesn't exist. + unset: function(attr, options) { + return this.set(attr, void 0, _.extend({}, options, {unset: true})); + }, + + // Clear all attributes on the model, firing `"change"`. + clear: function(options) { + var attrs = {}; + for (var key in this.attributes) attrs[key] = void 0; + return this.set(attrs, _.extend({}, options, {unset: true})); + }, + + // Determine if the model has changed since the last `"change"` event. + // If you specify an attribute name, determine if that attribute has changed. + hasChanged: function(attr) { + if (attr == null) return !_.isEmpty(this.changed); + return _.has(this.changed, attr); + }, + + // Return an object containing all the attributes that have changed, or + // false if there are no changed attributes. Useful for determining what + // parts of a view need to be updated and/or what attributes need to be + // persisted to the server. Unset attributes will be set to undefined. + // You can also pass an attributes object to diff against the model, + // determining if there *would be* a change. + changedAttributes: function(diff) { + if (!diff) return this.hasChanged() ? _.clone(this.changed) : false; + var val, changed = false; + var old = this._changing ? this._previousAttributes : this.attributes; + for (var attr in diff) { + if (_.isEqual(old[attr], (val = diff[attr]))) continue; + (changed || (changed = {}))[attr] = val; + } + return changed; + }, + + // Get the previous value of an attribute, recorded at the time the last + // `"change"` event was fired. + previous: function(attr) { + if (attr == null || !this._previousAttributes) return null; + return this._previousAttributes[attr]; + }, + + // Get all of the attributes of the model at the time of the previous + // `"change"` event. + previousAttributes: function() { + return _.clone(this._previousAttributes); + }, + + // Fetch the model from the server. If the server's representation of the + // model differs from its current attributes, they will be overridden, + // triggering a `"change"` event. + fetch: function(options) { + options = options ? _.clone(options) : {}; + if (options.parse === void 0) options.parse = true; + var model = this; + var success = options.success; + options.success = function(resp) { + if (!model.set(model.parse(resp, options), options)) return false; + if (success) success(model, resp, options); + model.trigger('sync', model, resp, options); + }; + wrapError(this, options); + return this.sync('read', this, options); + }, + + // Set a hash of model attributes, and sync the model to the server. + // If the server returns an attributes hash that differs, the model's + // state will be `set` again. + save: function(key, val, options) { + var attrs, method, xhr, attributes = this.attributes; + + // Handle both `"key", value` and `{key: value}` -style arguments. + if (key == null || typeof key === 'object') { + attrs = key; + options = val; + } else { + (attrs = {})[key] = val; + } + + options = _.extend({validate: true}, options); + + // If we're not waiting and attributes exist, save acts as + // `set(attr).save(null, opts)` with validation. Otherwise, check if + // the model will be valid when the attributes, if any, are set. + if (attrs && !options.wait) { + if (!this.set(attrs, options)) return false; + } else { + if (!this._validate(attrs, options)) return false; + } + + // Set temporary attributes if `{wait: true}`. + if (attrs && options.wait) { + this.attributes = _.extend({}, attributes, attrs); + } + + // After a successful server-side save, the client is (optionally) + // updated with the server-side state. + if (options.parse === void 0) options.parse = true; + var model = this; + var success = options.success; + options.success = function(resp) { + // Ensure attributes are restored during synchronous saves. + model.attributes = attributes; + var serverAttrs = model.parse(resp, options); + if (options.wait) serverAttrs = _.extend(attrs || {}, serverAttrs); + if (_.isObject(serverAttrs) && !model.set(serverAttrs, options)) { + return false; + } + if (success) success(model, resp, options); + model.trigger('sync', model, resp, options); + }; + wrapError(this, options); + + method = this.isNew() ? 'create' : (options.patch ? 'patch' : 'update'); + if (method === 'patch') options.attrs = attrs; + xhr = this.sync(method, this, options); + + // Restore attributes. + if (attrs && options.wait) this.attributes = attributes; + + return xhr; + }, + + // Destroy this model on the server if it was already persisted. + // Optimistically removes the model from its collection, if it has one. + // If `wait: true` is passed, waits for the server to respond before removal. + destroy: function(options) { + options = options ? _.clone(options) : {}; + var model = this; + var success = options.success; + + var destroy = function() { + model.trigger('destroy', model, model.collection, options); + }; + + options.success = function(resp) { + if (options.wait || model.isNew()) destroy(); + if (success) success(model, resp, options); + if (!model.isNew()) model.trigger('sync', model, resp, options); + }; + + if (this.isNew()) { + options.success(); + return false; + } + wrapError(this, options); + + var xhr = this.sync('delete', this, options); + if (!options.wait) destroy(); + return xhr; + }, + + // Default URL for the model's representation on the server -- if you're + // using Backbone's restful methods, override this to change the endpoint + // that will be called. + url: function() { + var base = _.result(this, 'urlRoot') || _.result(this.collection, 'url') || urlError(); + if (this.isNew()) return base; + return base + (base.charAt(base.length - 1) === '/' ? '' : '/') + encodeURIComponent(this.id); + }, + + // **parse** converts a response into the hash of attributes to be `set` on + // the model. The default implementation is just to pass the response along. + parse: function(resp, options) { + return resp; + }, + + // Create a new model with identical attributes to this one. + clone: function() { + return new this.constructor(this.attributes); + }, + + // A model is new if it has never been saved to the server, and lacks an id. + isNew: function() { + return this.id == null; + }, + + // Check if the model is currently in a valid state. + isValid: function(options) { + return this._validate({}, _.extend(options || {}, { validate: true })); + }, + + // Run validation against the next complete set of model attributes, + // returning `true` if all is well. Otherwise, fire an `"invalid"` event. + _validate: function(attrs, options) { + if (!options.validate || !this.validate) return true; + attrs = _.extend({}, this.attributes, attrs); + var error = this.validationError = this.validate(attrs, options) || null; + if (!error) return true; + this.trigger('invalid', this, error, _.extend(options || {}, {validationError: error})); + return false; + } + + }); + + // Underscore methods that we want to implement on the Model. + var modelMethods = ['keys', 'values', 'pairs', 'invert', 'pick', 'omit']; + + // Mix in each Underscore method as a proxy to `Model#attributes`. + _.each(modelMethods, function(method) { + Model.prototype[method] = function() { + var args = slice.call(arguments); + args.unshift(this.attributes); + return _[method].apply(_, args); + }; + }); + + // Backbone.Collection + // ------------------- + + // If models tend to represent a single row of data, a Backbone Collection is + // more analagous to a table full of data ... or a small slice or page of that + // table, or a collection of rows that belong together for a particular reason + // -- all of the messages in this particular folder, all of the documents + // belonging to this particular author, and so on. Collections maintain + // indexes of their models, both in order, and for lookup by `id`. + + // Create a new **Collection**, perhaps to contain a specific type of `model`. + // If a `comparator` is specified, the Collection will maintain + // its models in sort order, as they're added and removed. + var Collection = Backbone.Collection = function(models, options) { + options || (options = {}); + if (options.model) this.model = options.model; + if (options.comparator !== void 0) this.comparator = options.comparator; + this._reset(); + this.initialize.apply(this, arguments); + if (models) this.reset(models, _.extend({silent: true}, options)); + }; + + // Default options for `Collection#set`. + var setOptions = {add: true, remove: true, merge: true}; + var addOptions = {add: true, merge: false, remove: false}; + + // Define the Collection's inheritable methods. + _.extend(Collection.prototype, Events, { + + // The default model for a collection is just a **Backbone.Model**. + // This should be overridden in most cases. + model: Model, + + // Initialize is an empty function by default. Override it with your own + // initialization logic. + initialize: function(){}, + + // The JSON representation of a Collection is an array of the + // models' attributes. + toJSON: function(options) { + return this.map(function(model){ return model.toJSON(options); }); + }, + + // Proxy `Backbone.sync` by default. + sync: function() { + return Backbone.sync.apply(this, arguments); + }, + + // Add a model, or list of models to the set. + add: function(models, options) { + return this.set(models, _.defaults(options || {}, addOptions)); + }, + + // Remove a model, or a list of models from the set. + remove: function(models, options) { + models = _.isArray(models) ? models.slice() : [models]; + options || (options = {}); + var i, l, index, model; + for (i = 0, l = models.length; i < l; i++) { + model = this.get(models[i]); + if (!model) continue; + delete this._byId[model.id]; + delete this._byId[model.cid]; + index = this.indexOf(model); + this.models.splice(index, 1); + this.length--; + if (!options.silent) { + options.index = index; + model.trigger('remove', model, this, options); + } + this._removeReference(model); + } + return this; + }, + + // Update a collection by `set`-ing a new list of models, adding new ones, + // removing models that are no longer present, and merging models that + // already exist in the collection, as necessary. Similar to **Model#set**, + // the core operation for updating the data contained by the collection. + set: function(models, options) { + options = _.defaults(options || {}, setOptions); + if (options.parse) models = this.parse(models, options); + if (!_.isArray(models)) models = models ? [models] : []; + var i, l, model, attrs, existing, sort; + var at = options.at; + var sortable = this.comparator && (at == null) && options.sort !== false; + var sortAttr = _.isString(this.comparator) ? this.comparator : null; + var toAdd = [], toRemove = [], modelMap = {}; + var add = options.add, merge = options.merge, remove = options.remove; + var order = !sortable && add && remove ? [] : false; + + // Turn bare objects into model references, and prevent invalid models + // from being added. + for (i = 0, l = models.length; i < l; i++) { + if (!(model = this._prepareModel(attrs = models[i], options))) continue; + + // If a duplicate is found, prevent it from being added and + // optionally merge it into the existing model. + if (existing = this.get(model)) { + if (remove) modelMap[existing.cid] = true; + if (merge) { + attrs = attrs === model ? model.attributes : options._attrs; + existing.set(attrs, options); + if (sortable && !sort && existing.hasChanged(sortAttr)) sort = true; + } + + // This is a new model, push it to the `toAdd` list. + } else if (add) { + toAdd.push(model); + + // Listen to added models' events, and index models for lookup by + // `id` and by `cid`. + model.on('all', this._onModelEvent, this); + this._byId[model.cid] = model; + if (model.id != null) this._byId[model.id] = model; + } + if (order) order.push(existing || model); + } + + // Remove nonexistent models if appropriate. + if (remove) { + for (i = 0, l = this.length; i < l; ++i) { + if (!modelMap[(model = this.models[i]).cid]) toRemove.push(model); + } + if (toRemove.length) this.remove(toRemove, options); + } + + // See if sorting is needed, update `length` and splice in new models. + if (toAdd.length || (order && order.length)) { + if (sortable) sort = true; + this.length += toAdd.length; + if (at != null) { + splice.apply(this.models, [at, 0].concat(toAdd)); + } else { + if (order) this.models.length = 0; + push.apply(this.models, order || toAdd); + } + } + + // Silently sort the collection if appropriate. + if (sort) this.sort({silent: true}); + + if (options.silent) return this; + + // Trigger `add` events. + for (i = 0, l = toAdd.length; i < l; i++) { + (model = toAdd[i]).trigger('add', model, this, options); + } + + // Trigger `sort` if the collection was sorted. + if (sort || (order && order.length)) this.trigger('sort', this, options); + return this; + }, + + // When you have more items than you want to add or remove individually, + // you can reset the entire set with a new list of models, without firing + // any granular `add` or `remove` events. Fires `reset` when finished. + // Useful for bulk operations and optimizations. + reset: function(models, options) { + options || (options = {}); + for (var i = 0, l = this.models.length; i < l; i++) { + this._removeReference(this.models[i]); + } + options.previousModels = this.models; + this._reset(); + this.add(models, _.extend({silent: true}, options)); + if (!options.silent) this.trigger('reset', this, options); + return this; + }, + + // Add a model to the end of the collection. + push: function(model, options) { + model = this._prepareModel(model, options); + this.add(model, _.extend({at: this.length}, options)); + return model; + }, + + // Remove a model from the end of the collection. + pop: function(options) { + var model = this.at(this.length - 1); + this.remove(model, options); + return model; + }, + + // Add a model to the beginning of the collection. + unshift: function(model, options) { + model = this._prepareModel(model, options); + this.add(model, _.extend({at: 0}, options)); + return model; + }, + + // Remove a model from the beginning of the collection. + shift: function(options) { + var model = this.at(0); + this.remove(model, options); + return model; + }, + + // Slice out a sub-array of models from the collection. + slice: function() { + return slice.apply(this.models, arguments); + }, + + // Get a model from the set by id. + get: function(obj) { + if (obj == null) return void 0; + return this._byId[obj.id != null ? obj.id : obj.cid || obj]; + }, + + // Get the model at the given index. + at: function(index) { + return this.models[index]; + }, + + // Return models with matching attributes. Useful for simple cases of + // `filter`. + where: function(attrs, first) { + if (_.isEmpty(attrs)) return first ? void 0 : []; + return this[first ? 'find' : 'filter'](function(model) { + for (var key in attrs) { + if (attrs[key] !== model.get(key)) return false; + } + return true; + }); + }, + + // Return the first model with matching attributes. Useful for simple cases + // of `find`. + findWhere: function(attrs) { + return this.where(attrs, true); + }, + + // Force the collection to re-sort itself. You don't need to call this under + // normal circumstances, as the set will maintain sort order as each item + // is added. + sort: function(options) { + if (!this.comparator) throw new Error('Cannot sort a set without a comparator'); + options || (options = {}); + + // Run sort based on type of `comparator`. + if (_.isString(this.comparator) || this.comparator.length === 1) { + this.models = this.sortBy(this.comparator, this); + } else { + this.models.sort(_.bind(this.comparator, this)); + } + + if (!options.silent) this.trigger('sort', this, options); + return this; + }, + + // Figure out the smallest index at which a model should be inserted so as + // to maintain order. + sortedIndex: function(model, value, context) { + value || (value = this.comparator); + var iterator = _.isFunction(value) ? value : function(model) { + return model.get(value); + }; + return _.sortedIndex(this.models, model, iterator, context); + }, + + // Pluck an attribute from each model in the collection. + pluck: function(attr) { + return _.invoke(this.models, 'get', attr); + }, + + // Fetch the default set of models for this collection, resetting the + // collection when they arrive. If `reset: true` is passed, the response + // data will be passed through the `reset` method instead of `set`. + fetch: function(options) { + options = options ? _.clone(options) : {}; + if (options.parse === void 0) options.parse = true; + var success = options.success; + var collection = this; + options.success = function(resp) { + var method = options.reset ? 'reset' : 'set'; + collection[method](resp, options); + if (success) success(collection, resp, options); + collection.trigger('sync', collection, resp, options); + }; + wrapError(this, options); + return this.sync('read', this, options); + }, + + // Create a new instance of a model in this collection. Add the model to the + // collection immediately, unless `wait: true` is passed, in which case we + // wait for the server to agree. + create: function(model, options) { + options = options ? _.clone(options) : {}; + if (!(model = this._prepareModel(model, options))) return false; + if (!options.wait) this.add(model, options); + var collection = this; + var success = options.success; + options.success = function(resp) { + if (options.wait) collection.add(model, options); + if (success) success(model, resp, options); + }; + model.save(null, options); + return model; + }, + + // **parse** converts a response into a list of models to be added to the + // collection. The default implementation is just to pass it through. + parse: function(resp, options) { + return resp; + }, + + // Create a new collection with an identical list of models as this one. + clone: function() { + return new this.constructor(this.models); + }, + + // Private method to reset all internal state. Called when the collection + // is first initialized or reset. + _reset: function() { + this.length = 0; + this.models = []; + this._byId = {}; + }, + + // Prepare a hash of attributes (or other model) to be added to this + // collection. + _prepareModel: function(attrs, options) { + if (attrs instanceof Model) { + if (!attrs.collection) attrs.collection = this; + return attrs; + } + options || (options = {}); + options.collection = this; + var model = new this.model(attrs, options); + if (!model._validate(attrs, options)) { + this.trigger('invalid', this, attrs, options); + return false; + } + return model; + }, + + // Internal method to sever a model's ties to a collection. + _removeReference: function(model) { + if (this === model.collection) delete model.collection; + model.off('all', this._onModelEvent, this); + }, + + // Internal method called every time a model in the set fires an event. + // Sets need to update their indexes when models change ids. All other + // events simply proxy through. "add" and "remove" events that originate + // in other collections are ignored. + _onModelEvent: function(event, model, collection, options) { + if ((event === 'add' || event === 'remove') && collection !== this) return; + if (event === 'destroy') this.remove(model, options); + if (model && event === 'change:' + model.idAttribute) { + delete this._byId[model.previous(model.idAttribute)]; + if (model.id != null) this._byId[model.id] = model; + } + this.trigger.apply(this, arguments); + } + + }); + + // Underscore methods that we want to implement on the Collection. + // 90% of the core usefulness of Backbone Collections is actually implemented + // right here: + var methods = ['forEach', 'each', 'map', 'collect', 'reduce', 'foldl', + 'inject', 'reduceRight', 'foldr', 'find', 'detect', 'filter', 'select', + 'reject', 'every', 'all', 'some', 'any', 'include', 'contains', 'invoke', + 'max', 'min', 'toArray', 'size', 'first', 'head', 'take', 'initial', 'rest', + 'tail', 'drop', 'last', 'without', 'indexOf', 'shuffle', 'lastIndexOf', + 'isEmpty', 'chain']; + + // Mix in each Underscore method as a proxy to `Collection#models`. + _.each(methods, function(method) { + Collection.prototype[method] = function() { + var args = slice.call(arguments); + args.unshift(this.models); + return _[method].apply(_, args); + }; + }); + + // Underscore methods that take a property name as an argument. + var attributeMethods = ['groupBy', 'countBy', 'sortBy']; + + // Use attributes instead of properties. + _.each(attributeMethods, function(method) { + Collection.prototype[method] = function(value, context) { + var iterator = _.isFunction(value) ? value : function(model) { + return model.get(value); + }; + return _[method](this.models, iterator, context); + }; + }); + + // Backbone.View + // ------------- + + // Backbone Views are almost more convention than they are actual code. A View + // is simply a JavaScript object that represents a logical chunk of UI in the + // DOM. This might be a single item, an entire list, a sidebar or panel, or + // even the surrounding frame which wraps your whole app. Defining a chunk of + // UI as a **View** allows you to define your DOM events declaratively, without + // having to worry about render order ... and makes it easy for the view to + // react to specific changes in the state of your models. + + // Options with special meaning *(e.g. model, collection, id, className)* are + // attached directly to the view. See `viewOptions` for an exhaustive + // list. + + // Creating a Backbone.View creates its initial element outside of the DOM, + // if an existing element is not provided... + var View = Backbone.View = function(options) { + this.cid = _.uniqueId('view'); + options || (options = {}); + _.extend(this, _.pick(options, viewOptions)); + this._ensureElement(); + this.initialize.apply(this, arguments); + this.delegateEvents(); + }; + + // Cached regex to split keys for `delegate`. + var delegateEventSplitter = /^(\S+)\s*(.*)$/; + + // List of view options to be merged as properties. + var viewOptions = ['model', 'collection', 'el', 'id', 'attributes', 'className', 'tagName', 'events']; + + // Set up all inheritable **Backbone.View** properties and methods. + _.extend(View.prototype, Events, { + + // The default `tagName` of a View's element is `"div"`. + tagName: 'div', + + // jQuery delegate for element lookup, scoped to DOM elements within the + // current view. This should be prefered to global lookups where possible. + $: function(selector) { + return this.$el.find(selector); + }, + + // Initialize is an empty function by default. Override it with your own + // initialization logic. + initialize: function(){}, + + // **render** is the core function that your view should override, in order + // to populate its element (`this.el`), with the appropriate HTML. The + // convention is for **render** to always return `this`. + render: function() { + return this; + }, + + // Remove this view by taking the element out of the DOM, and removing any + // applicable Backbone.Events listeners. + remove: function() { + this.$el.remove(); + this.stopListening(); + return this; + }, + + // Change the view's element (`this.el` property), including event + // re-delegation. + setElement: function(element, delegate) { + if (this.$el) this.undelegateEvents(); + this.$el = element instanceof Backbone.$ ? element : Backbone.$(element); + this.el = this.$el[0]; + if (delegate !== false) this.delegateEvents(); + return this; + }, + + // Set callbacks, where `this.events` is a hash of + // + // *{"event selector": "callback"}* + // + // { + // 'mousedown .title': 'edit', + // 'click .button': 'save' + // 'click .open': function(e) { ... } + // } + // + // pairs. Callbacks will be bound to the view, with `this` set properly. + // Uses event delegation for efficiency. + // Omitting the selector binds the event to `this.el`. + // This only works for delegate-able events: not `focus`, `blur`, and + // not `change`, `submit`, and `reset` in Internet Explorer. + delegateEvents: function(events) { + if (!(events || (events = _.result(this, 'events')))) return this; + this.undelegateEvents(); + for (var key in events) { + var method = events[key]; + if (!_.isFunction(method)) method = this[events[key]]; + if (!method) continue; + + var match = key.match(delegateEventSplitter); + var eventName = match[1], selector = match[2]; + method = _.bind(method, this); + eventName += '.delegateEvents' + this.cid; + if (selector === '') { + this.$el.on(eventName, method); + } else { + this.$el.on(eventName, selector, method); + } + } + return this; + }, + + // Clears all callbacks previously bound to the view with `delegateEvents`. + // You usually don't need to use this, but may wish to if you have multiple + // Backbone views attached to the same DOM element. + undelegateEvents: function() { + this.$el.off('.delegateEvents' + this.cid); + return this; + }, + + // Ensure that the View has a DOM element to render into. + // If `this.el` is a string, pass it through `$()`, take the first + // matching element, and re-assign it to `el`. Otherwise, create + // an element from the `id`, `className` and `tagName` properties. + _ensureElement: function() { + if (!this.el) { + var attrs = _.extend({}, _.result(this, 'attributes')); + if (this.id) attrs.id = _.result(this, 'id'); + if (this.className) attrs['class'] = _.result(this, 'className'); + var $el = Backbone.$('<' + _.result(this, 'tagName') + '>').attr(attrs); + this.setElement($el, false); + } else { + this.setElement(_.result(this, 'el'), false); + } + } + + }); + + // Backbone.sync + // ------------- + + // Override this function to change the manner in which Backbone persists + // models to the server. You will be passed the type of request, and the + // model in question. By default, makes a RESTful Ajax request + // to the model's `url()`. Some possible customizations could be: + // + // * Use `setTimeout` to batch rapid-fire updates into a single request. + // * Send up the models as XML instead of JSON. + // * Persist models via WebSockets instead of Ajax. + // + // Turn on `Backbone.emulateHTTP` in order to send `PUT` and `DELETE` requests + // as `POST`, with a `_method` parameter containing the true HTTP method, + // as well as all requests with the body as `application/x-www-form-urlencoded` + // instead of `application/json` with the model in a param named `model`. + // Useful when interfacing with server-side languages like **PHP** that make + // it difficult to read the body of `PUT` requests. + Backbone.sync = function(method, model, options) { + var type = methodMap[method]; + + // Default options, unless specified. + _.defaults(options || (options = {}), { + emulateHTTP: Backbone.emulateHTTP, + emulateJSON: Backbone.emulateJSON + }); + + // Default JSON-request options. + var params = {type: type, dataType: 'json'}; + + // Ensure that we have a URL. + if (!options.url) { + params.url = _.result(model, 'url') || urlError(); + } + + // Ensure that we have the appropriate request data. + if (options.data == null && model && (method === 'create' || method === 'update' || method === 'patch')) { + params.contentType = 'application/json'; + params.data = JSON.stringify(options.attrs || model.toJSON(options)); + } + + // For older servers, emulate JSON by encoding the request into an HTML-form. + if (options.emulateJSON) { + params.contentType = 'application/x-www-form-urlencoded'; + params.data = params.data ? {model: params.data} : {}; + } + + // For older servers, emulate HTTP by mimicking the HTTP method with `_method` + // And an `X-HTTP-Method-Override` header. + if (options.emulateHTTP && (type === 'PUT' || type === 'DELETE' || type === 'PATCH')) { + params.type = 'POST'; + if (options.emulateJSON) params.data._method = type; + var beforeSend = options.beforeSend; + options.beforeSend = function(xhr) { + xhr.setRequestHeader('X-HTTP-Method-Override', type); + if (beforeSend) return beforeSend.apply(this, arguments); + }; + } + + // Don't process data on a non-GET request. + if (params.type !== 'GET' && !options.emulateJSON) { + params.processData = false; + } + + // If we're sending a `PATCH` request, and we're in an old Internet Explorer + // that still has ActiveX enabled by default, override jQuery to use that + // for XHR instead. Remove this line when jQuery supports `PATCH` on IE8. + if (params.type === 'PATCH' && window.ActiveXObject && + !(window.external && window.external.msActiveXFilteringEnabled)) { + params.xhr = function() { + return new ActiveXObject("Microsoft.XMLHTTP"); + }; + } + + // Make the request, allowing the user to override any Ajax options. + var xhr = options.xhr = Backbone.ajax(_.extend(params, options)); + model.trigger('request', model, xhr, options); + return xhr; + }; + + // Map from CRUD to HTTP for our default `Backbone.sync` implementation. + var methodMap = { + 'create': 'POST', + 'update': 'PUT', + 'patch': 'PATCH', + 'delete': 'DELETE', + 'read': 'GET' + }; + + // Set the default implementation of `Backbone.ajax` to proxy through to `$`. + // Override this if you'd like to use a different library. + Backbone.ajax = function() { + return Backbone.$.ajax.apply(Backbone.$, arguments); + }; + + // Backbone.Router + // --------------- + + // Routers map faux-URLs to actions, and fire events when routes are + // matched. Creating a new one sets its `routes` hash, if not set statically. + var Router = Backbone.Router = function(options) { + options || (options = {}); + if (options.routes) this.routes = options.routes; + this._bindRoutes(); + this.initialize.apply(this, arguments); + }; + + // Cached regular expressions for matching named param parts and splatted + // parts of route strings. + var optionalParam = /\((.*?)\)/g; + var namedParam = /(\(\?)?:\w+/g; + var splatParam = /\*\w+/g; + var escapeRegExp = /[\-{}\[\]+?.,\\\^$|#\s]/g; + + // Set up all inheritable **Backbone.Router** properties and methods. + _.extend(Router.prototype, Events, { + + // Initialize is an empty function by default. Override it with your own + // initialization logic. + initialize: function(){}, + + // Manually bind a single named route to a callback. For example: + // + // this.route('search/:query/p:num', 'search', function(query, num) { + // ... + // }); + // + route: function(route, name, callback) { + if (!_.isRegExp(route)) route = this._routeToRegExp(route); + if (_.isFunction(name)) { + callback = name; + name = ''; + } + if (!callback) callback = this[name]; + var router = this; + Backbone.history.route(route, function(fragment) { + var args = router._extractParameters(route, fragment); + callback && callback.apply(router, args); + router.trigger.apply(router, ['route:' + name].concat(args)); + router.trigger('route', name, args); + Backbone.history.trigger('route', router, name, args); + }); + return this; + }, + + // Simple proxy to `Backbone.history` to save a fragment into the history. + navigate: function(fragment, options) { + Backbone.history.navigate(fragment, options); + return this; + }, + + // Bind all defined routes to `Backbone.history`. We have to reverse the + // order of the routes here to support behavior where the most general + // routes can be defined at the bottom of the route map. + _bindRoutes: function() { + if (!this.routes) return; + this.routes = _.result(this, 'routes'); + var route, routes = _.keys(this.routes); + while ((route = routes.pop()) != null) { + this.route(route, this.routes[route]); + } + }, + + // Convert a route string into a regular expression, suitable for matching + // against the current location hash. + _routeToRegExp: function(route) { + route = route.replace(escapeRegExp, '\\$&') + .replace(optionalParam, '(?:$1)?') + .replace(namedParam, function(match, optional){ + return optional ? match : '([^\/]+)'; + }) + .replace(splatParam, '(.*?)'); + return new RegExp('^' + route + '$'); + }, + + // Given a route, and a URL fragment that it matches, return the array of + // extracted decoded parameters. Empty or unmatched parameters will be + // treated as `null` to normalize cross-browser behavior. + _extractParameters: function(route, fragment) { + var params = route.exec(fragment).slice(1); + return _.map(params, function(param) { + return param ? decodeURIComponent(param) : null; + }); + } + + }); + + // Backbone.History + // ---------------- + + // Handles cross-browser history management, based on either + // [pushState](http://diveintohtml5.info/history.html) and real URLs, or + // [onhashchange](https://developer.mozilla.org/en-US/docs/DOM/window.onhashchange) + // and URL fragments. If the browser supports neither (old IE, natch), + // falls back to polling. + var History = Backbone.History = function() { + this.handlers = []; + _.bindAll(this, 'checkUrl'); + + // Ensure that `History` can be used outside of the browser. + if (typeof window !== 'undefined') { + this.location = window.location; + this.history = window.history; + } + }; + + // Cached regex for stripping a leading hash/slash and trailing space. + var routeStripper = /^[#\/]|\s+$/g; + + // Cached regex for stripping leading and trailing slashes. + var rootStripper = /^\/+|\/+$/g; + + // Cached regex for detecting MSIE. + var isExplorer = /msie [\w.]+/; + + // Cached regex for removing a trailing slash. + var trailingSlash = /\/$/; + + // Has the history handling already been started? + History.started = false; + + // Set up all inheritable **Backbone.History** properties and methods. + _.extend(History.prototype, Events, { + + // The default interval to poll for hash changes, if necessary, is + // twenty times a second. + interval: 50, + + // Gets the true hash value. Cannot use location.hash directly due to bug + // in Firefox where location.hash will always be decoded. + getHash: function(window) { + var match = (window || this).location.href.match(/#(.*)$/); + return match ? match[1] : ''; + }, + + // Get the cross-browser normalized URL fragment, either from the URL, + // the hash, or the override. + getFragment: function(fragment, forcePushState) { + if (fragment == null) { + if (this._hasPushState || !this._wantsHashChange || forcePushState) { + fragment = this.location.pathname; + var root = this.root.replace(trailingSlash, ''); + if (!fragment.indexOf(root)) fragment = fragment.substr(root.length); + } else { + fragment = this.getHash(); + } + } + return fragment.replace(routeStripper, ''); + }, + + // Start the hash change handling, returning `true` if the current URL matches + // an existing route, and `false` otherwise. + start: function(options) { + if (History.started) throw new Error("Backbone.history has already been started"); + History.started = true; + + // Figure out the initial configuration. Do we need an iframe? + // Is pushState desired ... is it available? + this.options = _.extend({}, {root: '/'}, this.options, options); + this.root = this.options.root; + this._wantsHashChange = this.options.hashChange !== false; + this._wantsPushState = !!this.options.pushState; + this._hasPushState = !!(this.options.pushState && this.history && this.history.pushState); + var fragment = this.getFragment(); + var docMode = document.documentMode; + var oldIE = (isExplorer.exec(navigator.userAgent.toLowerCase()) && (!docMode || docMode <= 7)); + + // Normalize root to always include a leading and trailing slash. + this.root = ('/' + this.root + '/').replace(rootStripper, '/'); + + if (oldIE && this._wantsHashChange) { + this.iframe = Backbone.$('