Source: src/walker.js

  1. /**
  2.  * Traversal utilities for ASTs that are compatible with the Mozilla Parser API. Adapted from
  3.  * [Acorn](http://marijnhaverbeke.nl/acorn/).
  4.  *
  5.  * @module jsdoc/src/walker
  6.  * @license MIT
  7.  */
  8. 'use strict';
  10. var astnode = require('jsdoc/src/astnode');
  11. var doclet = require('jsdoc/doclet');
  12. var Syntax = require('jsdoc/src/syntax').Syntax;
  14. /**
  15.  * Check whether an AST node creates a new scope.
  16.  *
  17.  * @private
  18.  * @param {Object} node - The AST node to check.
  19.  * @return {Boolean} Set to `true` if the node creates a new scope, or `false` in all other cases.
  20.  */
  21. function isScopeNode(node) {
  22.     // TODO: handle blocks with "let" declarations
  23.     return node && typeof node === 'object' && (node.type === Syntax.CatchClause ||
  24.         node.type === Syntax.FunctionDeclaration || node.type === Syntax.FunctionExpression ||
  25.         node.type === Syntax.ArrowFunctionExpression);
  26. }
  28. // TODO: docs
  29. function getCurrentScope(scopes) {
  30.     return scopes[scopes.length - 1] || null;
  31. }
  33. // TODO: docs
  34. function moveComments(source, target) {
  35.     if (source.leadingComments) {
  36.         target.leadingComments = source.leadingComments.slice(0);
  37.         source.leadingComments = [];
  38.     }
  39. }
  41. function leafNode(node, parent, state, cb) {}
  43. // TODO: docs
  44. var walkers = exports.walkers = {};
  46. walkers[Syntax.ArrayExpression] = function(node, parent, state, cb) {
  47.     for (var i = 0, l = node.elements.length; i < l; i++) {
  48.         var e = node.elements[i];
  49.         if (e) {
  50.             cb(e, node, state);
  51.         }
  52.     }
  53. };
  55. // TODO: verify correctness
  56. walkers[Syntax.ArrayPattern] = function(node, parent, state, cb) {
  57.     for (var i = 0, l = node.elements.length; i < l; i++) {
  58.         var e = node.elements[i];
  59.         // must be an identifier or an expression
  60.         if (e && e.type !== Syntax.Identifier) {
  61.             cb(e, node, state);
  62.         }
  63.     }
  64. };
  66. walkers[Syntax.ArrowFunctionExpression] = function(node, parent, state, cb) {
  67.     var i;
  68.     var l;
  70.     if (node.id) {
  71.         cb(node.id, node, state);
  72.     }
  74.     for (i = 0, l = node.params.length; i < l; i++) {
  75.         cb(node.params[i], node, state);
  76.     }
  78.     cb(node.body, node, state);
  79. };
  81. walkers[Syntax.AssignmentExpression] = function(node, parent, state, cb) {
  82.     cb(node.left, node, state);
  83.     cb(node.right, node, state);
  84. };
  86. walkers[Syntax.AssignmentPattern] = walkers[Syntax.AssignmentExpression];
  88. walkers[Syntax.BinaryExpression] = function(node, parent, state, cb) {
  89.     cb(node.left, node, state);
  90.     cb(node.right, node, state);
  91. };
  93. walkers[Syntax.BlockStatement] = function(node, parent, state, cb) {
  94.     for (var i = 0, l = node.body.length; i < l; i++) {
  95.         cb(node.body[i], node, state);
  96.     }
  97. };
  99. walkers[Syntax.BreakStatement] = leafNode;
  101. walkers[Syntax.CallExpression] = function(node, parent, state, cb) {
  102.     var i;
  103.     var l;
  105.     cb(node.callee, node, state);
  106.     if (node.arguments) {
  107.         for (i = 0, l = node.arguments.length; i < l; i++) {
  108.             cb(node.arguments[i], node, state);
  109.         }
  110.     }
  111. };
  113. walkers[Syntax.CatchClause] = leafNode;
  115. walkers[Syntax.ClassBody] = walkers[Syntax.BlockStatement];
  117. walkers[Syntax.ClassDeclaration] = function(node, parent, state, cb) {
  118.     if (node.id) {
  119.         cb(node.id, node, state);
  120.     }
  122.     if (node.superClass) {
  123.         cb(node.superClass, node, state);
  124.     }
  126.     if (node.body) {
  127.         cb(node.body, node, state);
  128.     }
  129. };
  131. walkers[Syntax.ClassExpression] = walkers[Syntax.ClassDeclaration];
  133. // TODO: verify correctness
  134. walkers[Syntax.ComprehensionBlock] = walkers[Syntax.AssignmentExpression];
  136. // TODO: verify correctness
  137. walkers[Syntax.ComprehensionExpression] = function(node, parent, state, cb) {
  138.     cb(node.body, node, state);
  140.     if (node.filter) {
  141.         cb(node.filter, node, state);
  142.     }
  144.     for (var i = 0, l = node.blocks.length; i < l; i++) {
  145.         cb(node.blocks[i], node, state);
  146.     }
  147. };
  149. walkers[Syntax.ConditionalExpression] = function(node, parent, state, cb) {
  150.     cb(node.test, node, state);
  151.     cb(node.consequent, node, state);
  152.     cb(node.alternate, node, state);
  153. };
  155. walkers[Syntax.ContinueStatement] = leafNode;
  157. walkers[Syntax.DebuggerStatement] = leafNode;
  159. walkers[Syntax.DoWhileStatement] = function(node, parent, state, cb) {
  160.     cb(node.test, node, state);
  161.     cb(node.body, node, state);
  162. };
  164. walkers[Syntax.EmptyStatement] = leafNode;
  166. walkers[Syntax.ExperimentalRestProperty] = function(node, parent, state, cb) {
  167.     cb(node.argument);
  168. };
  170. walkers[Syntax.ExperimentalSpreadProperty] = walkers[Syntax.ExperimentalRestProperty];
  172. walkers[Syntax.ExportAllDeclaration] = function(node, parent, state, cb) {
  173.     if (node.source) {
  174.         cb(node.source, node, state);
  175.     }
  176. };
  178. walkers[Syntax.ExportDefaultDeclaration] = function(node, parent, state, cb) {
  179.     if (node.declaration) {
  180.         cb(node.declaration, node, state);
  181.     }
  182. };
  184. walkers[Syntax.ExportNamedDeclaration] = function(node, parent, state, cb) {
  185.     var i;
  186.     var l;
  188.     if (node.declaration) {
  189.         cb(node.declaration, node, state);
  190.     }
  192.     for (i = 0, l = node.specifiers.length; i < l; i++) {
  193.         cb(node.specifiers[i], node, state);
  194.     }
  196.     if (node.source) {
  197.         cb(node.source, node, state);
  198.     }
  199. };
  201. walkers[Syntax.ExportSpecifier] = function(node, parent, state, cb) {
  202.     if (node.exported) {
  203.         cb(node.exported, node, state);
  204.     }
  206.     if (node.local) {
  207.         cb(node.local, node, state);
  208.     }
  209. };
  211. walkers[Syntax.ExpressionStatement] = function(node, parent, state, cb) {
  212.     cb(node.expression, node, state);
  213. };
  215. walkers[Syntax.ForInStatement] = function(node, parent, state, cb) {
  216.     cb(node.left, node, state);
  217.     cb(node.right, node, state);
  218.     cb(node.body, node, state);
  219. };
  221. walkers[Syntax.ForOfStatement] = walkers[Syntax.ForInStatement];
  223. walkers[Syntax.ForStatement] = function(node, parent, state, cb) {
  224.     if (node.init) {
  225.         cb(node.init, node, state);
  226.     }
  228.     if (node.test) {
  229.         cb(node.test, node, state);
  230.     }
  232.     if (node.update) {
  233.         cb(node.update, node, state);
  234.     }
  236.     cb(node.body, node, state);
  237. };
  239. walkers[Syntax.FunctionDeclaration] = walkers[Syntax.ArrowFunctionExpression];
  241. walkers[Syntax.FunctionExpression] = walkers[Syntax.ArrowFunctionExpression];
  243. walkers[Syntax.Identifier] = leafNode;
  245. walkers[Syntax.IfStatement] = function(node, parent, state, cb) {
  246.     cb(node.test, node, state);
  247.     cb(node.consequent, node, state);
  248.     if (node.alternate) {
  249.         cb(node.alternate, node, state);
  250.     }
  251. };
  253. walkers[Syntax.ImportDeclaration] = function(node, parent, state, cb) {
  254.     if (node.specifiers) {
  255.         for (var i = 0, l = node.specifiers.length; i < l; i++) {
  256.             cb(node.specifiers[i], node, state);
  257.         }
  258.     }
  260.     if (node.source) {
  261.         cb(node.source, node, state);
  262.     }
  263. };
  265. walkers[Syntax.ImportDefaultSpecifier] = function(node, parent, state, cb) {
  266.     if (node.local) {
  267.         cb(node.local, node, state);
  268.     }
  269. };
  271. walkers[Syntax.ImportNamespaceSpecifier] = walkers[Syntax.ImportDefaultSpecifier];
  273. walkers[Syntax.ImportSpecifier] = walkers[Syntax.ExportSpecifier];
  275. walkers[Syntax.JSXAttribute] = function(node, parent, state, cb) {
  276.     cb(node.name, node, state);
  278.     cb(node.value, node, state);
  279. };
  281. walkers[Syntax.JSXClosingElement] = function(node, parent, state, cb) {
  282.     cb(node.name, node, state);
  283. };
  285. walkers[Syntax.JSXElement] = function(node, parent, state, cb) {
  286.     cb(node.openingElement, node, state);
  288.     if (node.closingElement) {
  289.         cb(node.closingElement, node, state);
  290.     }
  292.     for (var i = 0, l = node.children.length; i < l; i++) {
  293.         cb(node.children[i], node, state);
  294.     }
  295. };
  297. walkers[Syntax.JSXEmptyExpression] = leafNode;
  299. walkers[Syntax.JSXExpressionContainer] = function(node, parent, state, cb) {
  300.     cb(node.expression, node, state);
  301. };
  303. walkers[Syntax.JSXIdentifier] = leafNode;
  305. walkers[Syntax.JSXMemberExpression] = function(node, parent, state, cb) {
  306.     cb(node.object, node, state);
  308.     cb(node.property, node, state);
  309. };
  311. walkers[Syntax.JSXNamespacedName] = function(node, parent, state, cb) {
  312.     cb(node.namespace, node, state);
  314.     cb(node.name, node, state);
  315. };
  317. walkers[Syntax.JSXOpeningElement] = function(node, parent, state, cb) {
  318.     cb(node.name, node, state);
  320.     for (var i = 0, l = node.attributes.length; i < l; i++) {
  321.         cb(node.attributes[i], node, state);
  322.     }
  323. };
  325. walkers[Syntax.JSXSpreadAttribute] = function(node, parent, state, cb) {
  326.     cb(node.argument, node, state);
  327. };
  329. walkers[Syntax.JSXText] = leafNode;
  331. walkers[Syntax.LabeledStatement] = function(node, parent, state, cb) {
  332.     cb(node.body, node, state);
  333. };
  335. // TODO: add scope info??
  336. walkers[Syntax.LetStatement] = function(node, parent, state, cb) {
  337.     for (var i = 0, l = node.head.length; i < l; i++) {
  338.         var head = node.head[i];
  339.         cb(head.id, node, state);
  340.         if (head.init) {
  341.             cb(head.init, node, state);
  342.         }
  343.     }
  345.     cb(node.body, node, state);
  346. };
  348. walkers[Syntax.Literal] = leafNode;
  350. walkers[Syntax.LogicalExpression] = walkers[Syntax.BinaryExpression];
  352. walkers[Syntax.MemberExpression] = function(node, parent, state, cb) {
  353.     cb(node.object, node, state);
  354.     if (node.property) {
  355.         cb(node.property, node, state);
  356.     }
  357. };
  359. walkers[Syntax.MetaProperty] = leafNode;
  361. walkers[Syntax.MethodDefinition] = function(node, parent, state, cb) {
  362.     if (node.key) {
  363.         cb(node.key, node, state);
  364.     }
  366.     if (node.value) {
  367.         cb(node.value, node, state);
  368.     }
  369. };
  371. walkers[Syntax.ModuleDeclaration] = function(node, parent, state, cb) {
  372.     if (node.id) {
  373.         cb(node.id, node, state);
  374.     }
  376.     if (node.source) {
  377.         cb(node.source, node, state);
  378.     }
  380.     if (node.body) {
  381.         cb(node.body, node, state);
  382.     }
  383. };
  385. walkers[Syntax.NewExpression] = walkers[Syntax.CallExpression];
  387. walkers[Syntax.ObjectExpression] = function(node, parent, state, cb) {
  388.     for (var i = 0, l = node.properties.length; i < l; i++) {
  389.         cb(node.properties[i], node, state);
  390.     }
  391. };
  393. walkers[Syntax.ObjectPattern] = walkers[Syntax.ObjectExpression];
  395. walkers[Syntax.Program] = walkers[Syntax.BlockStatement];
  397. walkers[Syntax.Property] = function(node, parent, state, cb) {
  398.     // move leading comments from key to property node
  399.     moveComments(node.key, node);
  401.     cb(node.value, node, state);
  402. };
  404. walkers[Syntax.RestElement] = function(node, parent, state, cb) {
  405.     if (node.argument) {
  406.         cb(node.argument, node, state);
  407.     }
  408. };
  410. walkers[Syntax.ReturnStatement] = function(node, parent, state, cb) {
  411.     if (node.argument) {
  412.         cb(node.argument, node, state);
  413.     }
  414. };
  416. walkers[Syntax.SequenceExpression] = function(node, parent, state, cb) {
  417.     for (var i = 0, l = node.expressions.length; i < l; i++) {
  418.         cb(node.expressions[i], node, state);
  419.     }
  420. };
  422. walkers[Syntax.SpreadElement] = function(node, parent, state, cb) {
  423.     if (node.argument) {
  424.         cb(node.argument, node, state);
  425.     }
  426. };
  428. walkers[Syntax.Super] = leafNode;
  430. walkers[Syntax.SwitchCase] = function(node, parent, state, cb) {
  431.     if (node.test) {
  432.         cb(node.test, node, state);
  433.     }
  435.     for (var i = 0, l = node.consequent.length; i < l; i++) {
  436.         cb(node.consequent[i], node, state);
  437.     }
  438. };
  440. walkers[Syntax.SwitchStatement] = function(node, parent, state, cb) {
  441.     cb(node.discriminant, node, state);
  443.     for (var i = 0, l = node.cases.length; i < l; i++) {
  444.         cb(node.cases[i], node, state);
  445.     }
  446. };
  448. walkers[Syntax.TaggedTemplateExpression] = function(node, parent, state, cb) {
  449.     if (node.tag) {
  450.         cb(node.tag, node, state);
  451.     }
  452.     if (node.quasi) {
  453.         cb(node.quasi, node, state);
  454.     }
  455. };
  457. walkers[Syntax.TemplateElement] = leafNode;
  459. walkers[Syntax.TemplateLiteral] = function(node, parent, state, cb) {
  460.     var i;
  461.     var l;
  463.     if (node.quasis && node.quasis.length) {
  464.         for (i = 0, l = node.quasis.length; i < l; i++) {
  465.             cb(node.quasis[i], node, state);
  466.         }
  467.     }
  469.     if (node.expressions && node.expressions.length) {
  470.         for (i = 0, l = node.expressions.length; i < l; i++) {
  471.             cb(node.expressions[i], node, state);
  472.         }
  473.     }
  474. };
  476. walkers[Syntax.ThisExpression] = leafNode;
  478. walkers[Syntax.ThrowStatement] = function(node, parent, state, cb) {
  479.     cb(node.argument, node, state);
  480. };
  482. walkers[Syntax.TryStatement] = function(node, parent, state, cb) {
  483.     var i;
  484.     var l;
  486.     cb(node.block, node, state);
  488.     if (node.handler) {
  489.         cb(node.handler.body, node, state);
  490.     }
  492.     if (node.finalizer) {
  493.         cb(node.finalizer, node, state);
  494.     }
  495. };
  497. walkers[Syntax.UnaryExpression] = function(node, parent, state, cb) {
  498.     cb(node.argument, node, state);
  499. };
  501. walkers[Syntax.UpdateExpression] = walkers[Syntax.UnaryExpression];
  503. walkers[Syntax.VariableDeclaration] = function(node, parent, state, cb) {
  504.     // move leading comments to first declarator
  505.     moveComments(node, node.declarations[0]);
  507.     for (var i = 0, l = node.declarations.length; i < l; i++) {
  508.         cb(node.declarations[i], node, state);
  509.     }
  510. };
  512. walkers[Syntax.VariableDeclarator] = function(node, parent, state, cb) {
  513.     cb(node.id, node, state);
  515.     if (node.init) {
  516.         cb(node.init, node, state);
  517.     }
  518. };
  520. walkers[Syntax.WhileStatement] = walkers[Syntax.DoWhileStatement];
  522. walkers[Syntax.WithStatement] = function(node, parent, state, cb) {
  523.     cb(node.object, node, state);
  524.     cb(node.body, node, state);
  525. };
  527. walkers[Syntax.YieldExpression] = function(node, parent, state, cb) {
  528.     if (node.argument) {
  529.         cb(node.argument, node, state);
  530.     }
  531. };
  533. /**
  534.  * Create a walker that can traverse an AST that is consistent with the Mozilla Parser API.
  535.  *
  536.  * @todo docs
  537.  * @memberof module:jsdoc/src/walker
  538.  */
  539. var Walker = exports.Walker = function(walkerFuncs) {
  540.     this._walkers = walkerFuncs || walkers;
  541. };
  543. // TODO: docs
  544. Walker.prototype._recurse = function(filename, ast) {
  545.     var self = this;
  546.     var state = {
  547.         filename: filename,
  548.         nodes: [],
  549.         scopes: []
  550.     };
  552.     function cb(node, parent, cbState) {
  553.         var currentScope;
  555.         var isScope = astnode.isScope(node);
  557.         astnode.addNodeProperties(node);
  558.         node.parent = parent || null;
  560.         currentScope = getCurrentScope(cbState.scopes);
  561.         if (currentScope) {
  562.             node.enclosingScope = currentScope;
  563.         }
  565.         if (isScope) {
  566.             cbState.scopes.push(node);
  567.         }
  568.         cbState.nodes.push(node);
  570.         self._walkers[node.type](node, parent, cbState, cb);
  572.         if (isScope) {
  573.             cbState.scopes.pop();
  574.         }
  575.     }
  577.     cb(ast, null, state);
  579.     return state;
  580. };
  582. // TODO: docs
  583. // TODO: skip the AST root node to be consistent with Rhino?
  584. Walker.prototype.recurse = function(ast, visitor, filename) {
  585.     var shouldContinue;
  586.     var state = this._recurse(filename, ast);
  588.     if (visitor) {
  589.         for (var i = 0, l = state.nodes.length; i < l; i++) {
  590.             shouldContinue = visitor.visit.call(visitor, state.nodes[i], filename);
  591.             if (!shouldContinue) {
  592.                 break;
  593.             }
  594.         }
  595.     }
  597.     return ast;
  598. };