AST 类型

本模块提供了一个高效、模块化的 Esprima 兼容实现，用于实现由 Mozilla 解析器 API 开创的抽象语法树类型层次结构。

安装

通过 NPM:

npm install ast-types

从 GitHub:

cd path/to/node_modules
git clone git://github.com/benjamn/ast-types.git
cd ast-types
npm install .

基本用法

import assert from "assert";
import {
  namedTypes as n,
  builders as b,
} from "ast-types";

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 遍历

由于该库深入理解 AST 类型系统，因此能够提供出色的节点迭代和遍历机制。

如果你想完全控制遍历过程，只需要一种枚举 AST 节点已知字段并获取其值的方法，你可能会对 getFieldNames 和 getFieldValue 这两个基础函数感兴趣:

import {
  getFieldNames,
  getFieldValue,
} from "ast-types";

const partialFunExpr = { type: "FunctionExpression" };

// 尽管 partialFunExpr 实际上并不包含 FunctionExpression 所需的所有字段，
// types.getFieldNames 依然知道:
console.log(getFieldNames(partialFunExpr));
// [ 'type', 'id', 'params', 'body', 'generator', 'expression',
//   'defaults', 'rest', 'async' ]

// 对于具有默认值的字段，如果该字段未实际定义，types.getFieldValue 将返回默认值。
console.log(getFieldValue(partialFunExpr, "generator"));
// false

另外两个低级辅助函数 eachField 和 someField 是基于 getFieldNames 和 getFieldValue 定义的:

// 遍历对象的所有已定义字段，包括缺失或未定义的字段，
// 将每个字段名和有效值（由 getFieldValue 返回）传递给回调函数。
// 如果对象没有相应的 Def，则不会调用回调函数。
export function eachField(object, callback, context) {
  getFieldNames(object).forEach(function(name) {
    callback.call(this, name, getFieldValue(object, name));
  }, context);
}

// 类似于 eachField，但一旦回调函数返回真值就停止迭代。
// 与 Array.prototype.some 类似，最终结果为 true 或 false，
// 表示回调函数是否对任何元素返回了 true。
export function someField(object, callback, context) {
  return getFieldNames(object).some(function(name) {
    return callback.call(this, name, getFieldValue(object, name));
  }, context);
}

下面是如何复制 AST 节点的示例:

import { eachField } from "ast-types";
const copy = {};
eachField(node, function(name, value) {
  // 注意，未定义的字段也会根据 node.type 的相关规则被访问，
  // 并在适当时替换为默认字段值。
  copy[name] = value;
})

但这还不是全部！你还可以使用强大的 types.visit 抽象轻松访问整个语法树。

这里是一个简单的例子，展示如何断言 ast 中从未使用 arguments.callee:

import assert from "assert";
import {
  visit,
  namedTypes as n,
} from "ast-types";

visit(ast, {
  // 这个方法将被调用于任何 .type 为 "MemberExpression" 的节点:
  visitMemberExpression(path) {
    // 访问方法接收一个参数，一个包装感兴趣节点的 NodePath 对象。
    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");
    }

    // 在访问方法返回之前，你有责任使用某个 NodePath 对象
    //（通常是传入访问方法的对象）调用 this.traverse，
    // 或者返回 false 以表明遍历不需要继续深入这个子树。
    this.traverse(path);
  }
});

这里是一个稍微复杂一点的例子，将 ...rest 参数转换为可在浏览器中运行的 ES5 JavaScript:

import { builders as b, visit } from "ast-types";

// 重用相同的 AST 结构来表示 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
);

visit(ast, {
  // 这个方法将被调用于任何类型是 Function 子类型的节点
  //（例如 FunctionDeclaration、FunctionExpression 和 ArrowFunctionExpression）。
  // 注意，types.visit 预先计算了一个查找表，
  // 从每个已知类型到适当的访问方法，因此调度时间是常数。
  visitFunction(path) {
    // 访问方法接收一个参数，一个包装感兴趣节点的 NodePath 对象。
    const node = path.node;

    // 在访问方法返回之前，你有责任使用某个 NodePath 对象
    //（通常是传入访问方法的对象）调用 this.traverse，
    // 或者返回 false 以表明遍历不需要继续深入这个子树。
    // 如果你忘记了，将会触发断言失败，这很棒，
    // 因为这意味着你永远不会再犯忘记遍历子树这个灾难性错误。
    // 同样很酷的是：因为你可以在访问方法的任何位置调用这个方法，
    // 所以由你决定遍历是前序、后序还是两者兼有！
    this.traverse(path);

    // 这个遍历只关心有 rest 参数的 Function 节点。
    if (!node.rest) {
      return;
    }

    // 就本例而言，我们不会考虑有 Expression 主体的函数。
    n.BlockStatement.assert(node.body);

    // 使用 types.builders 构建一个变量声明，形式如下：
    //
    //   var rest = Array.prototype.slice.call(arguments, n);
    //
    // 其中 `rest` 是 rest 参数的名称，`n` 是一个数字字面量，
    // 指定函数接受的命名参数数量。
    const restVarDecl = b.variableDeclaration("var", [
      b.variableDeclarator(
        node.rest,
        b.callExpression(sliceExpr, [
          b.identifier("arguments"),
          b.literal(node.params.length)
        ])
      )
    ]);

    // 类似于执行 node.body.body.unshift(restVarDecl)，
    // 但包装其他 body 语句的 NodePath 对象
    // 会更新它们的索引以适应新语句。
    path.get("body", "body").unshift(restVarDecl);

    // 现在我们已经用普通 JavaScript 模拟了 rest 参数的行为，
    // 将 node.rest 置为 null。
    path.get("rest").replace(null);

    // 直接执行 node.rest = null 也没问题，
    // 但我想指出上面的语句具有相同的效果。
    assert.strictEqual(node.rest, null);
  }
});

下面是如何使用 types.visit 来实现一个函数，该函数判断给定的函数节点是否引用了 this:

function usesThis(funcNode) {
  n.Function.assert(funcNode);
  var result = false;

  visit(funcNode, {
    visitThisExpression(path) {
      result = true;

      // 终止遍历的最快方法是调用 this.abort()，
      // 它会抛出一个特殊的异常（instanceof this.AbortRequest），
      // 该异常将在顶层 types.visit 方法中被捕获，
      // 因此你不必担心自己捕获异常。
      this.abort();
    },

    visitFunction(path) {
      // 嵌套作用域中的 ThisExpression 节点不算作原始函数节点的 `this` 引用，
      // 所以我们可以安全地避免遍历这个子树。
      return false;
    },

    visitCallExpression(path) {
      const node = path.node;

      // 如果函数包含涉及 super 的 CallExpression 节点，
      // 这些表达式将隐式依赖 `this` 的值，
      // 即使它们并不显式包含任何 ThisExpression 节点。
      if (this.isSuperCallExpression(node)) {
        result = true;
        this.abort(); // 抛出 AbortRequest 异常。
      }

      this.traverse(path);
    },

    // 是的，你可以定义任意的辅助方法。
    isSuperCallExpression(callExpr) {
      n.CallExpression.assert(callExpr);
      return this.isSuperIdentifier(callExpr.callee)
          || this.isSuperMemberExpression(callExpr.callee);
    },

    // 甚至可以定义辅助方法的辅助方法！
    isSuperIdentifier(node) {
      return n.Identifier.check(node.callee)
          && node.callee.name === "super";
    },

    isSuperMemberExpression(node) {
      return n.MemberExpression.check(node.callee)
          && n.Identifier.check(node.callee.object)
          && node.callee.object.name === "super";
    }
  });

  return result;
}

你可能猜到了，当从子树抛出 AbortRequest 时，异常将从祖先访问方法中相应的 this.traverse 调用传播。如果你决定要取消请求，只需捕获异常并调用其 .cancel() 方法。try-catch 块下面的子树的剩余部分将被放弃，但祖先节点的剩余兄弟节点仍将被访问。

NodePath

传递给访问方法的 NodePath 对象是 AST 节点的包装器，它提供了对祖先对象链（一直到 AST 的根）和作用域信息的访问。

通常，path.node 指的是被包装的节点，path.parent.node 指的是最近的 Node 祖先，path.parent.parent.node 指的是祖父节点，依此类推。

注意，path.node 可能不是 path.parent.node 的直接属性值；例如，可能是 path.node 是父节点的一个数组的元素：

path.node === path.parent.node.elements[3]

在这种情况下，你应该知道 path.parentPath 提供了从 AST 根到完整对象路径（不仅仅是 Node 对象）的更细粒度访问：

// 实际上，path.parent 是 path 的祖父：
path.parentPath.parentPath === path.parent

// path.parentPath 对象包装了 elements 数组（注意我们使用 .value，
// 因为 elements 数组不是一个 Node）：
path.parentPath.value === path.parent.node.elements

// path.node 对象是该数组的第四个元素：
path.parentPath.value[3] === path.node

// 与 path.node 和 path.value 不同，它们是同义词，因为 path.node 是一个 Node 对象，
// path.parentPath.node 与 path.parentPath.value 是不同的，因为 elements 数组不是一个 Node。
// 相反，path.parentPath.node 指的是最近的祖先 Node，
// 恰好与 path.parent.node 相同：
path.parentPath.node === path.parent.node

// path 的名称是它在 elements 数组中的索引：
path.name === 3

// 同样，path.parentPath 的名称是 path.parent.node 引用它的属性：
path.parentPath.name === "elements"

// 把它们放在一起，我们可以通过按名称访问每个属性，
// 从 path.parent.node 一直追踪对象引用链到 path.node
子 `NodePath` 对象是通过调用父 `NodePath` 对象的 `.get` 方法懒加载创建的：

```js
// 如果之前从未创建过 elements 数组的 NodePath 对象，
// 它将在此处创建并在未来被缓存：
path.get("elements").get(3).value === path.value.elements[3]

// 或者，你可以向 .get 传递多个属性名，而不是链式调用多个 .get：
path.get("elements", 0).value === path.value.elements[0]

NodePath 对象支持许多有用的方法：

// 用另一个节点替换一个节点：
var fifth = path.get("elements", 4);
fifth.replace(newNode);

// 现在执行一些可能重排列表的操作，这个替换仍然是安全的：
fifth.replace(newerNode);

// 用两个新节点替换数组中的第三个元素：
path.get("elements", 2).replace(
  b.identifier("foo"),
  b.thisExpression()
);

// 移除一个节点，如果会留下冗余的 AST 节点，则同时移除其父节点：
// 例如 var t = 1, y = 2; 移除 `t` 和 `y` 声明会导致 `var undefined`。
path.prune(); // 返回最近的父 `NodePath`。

// 从节点列表中移除一个节点：
path.get("elements", 3).replace();

// 在节点列表的开头添加三个新节点：
path.get("elements").unshift(a, b, c);

// 移除并返回节点列表中的第一个节点：
path.get("elements").shift();

// 在节点列表的末尾推入两个新节点：
path.get("elements").push(d, e);

// 移除并返回节点列表中的最后一个节点：
path.get("elements").pop();

// 在节点列表的第七个节点之前/之后插入一个新节点：
var seventh = path.get("elements", 6);
seventh.insertBefore(newNode);
seventh.insertAfter(newNode);

// 在节点列表的索引 5 处插入一个新元素：
path.get("elements").insertAt(5, newNode);

作用域

在 AST 遍历过程中，作为 path.scope 暴露的对象提供了关于包含 path.node 的作用域中变量和函数声明的信息。查看 scope.ts 了解其公共接口，目前包括 .isGlobal、.getGlobalScope()、.depth、.declares(name)、.lookup(name) 和 .getBindings()。

自定义 AST 节点类型

ast-types 模块设计为可扩展的。为此，它提供了一种可读、声明式的语法来指定新的 AST 节点类型，主要基于 require("ast-types").Type.def 函数：

import {
  Type,
  builtInTypes,
  builders as b,
  finalize,
} from "ast-types";

const { def } = Type;
const { string } = builtInTypes;

// 假设你需要一个命名的 File 类型来包装你的 Programs。
def("File")
  .bases("Node")
  .build("name", "program")
  .field("name", string)
  .field("program", def("Program"));

// 防止对 File 类型（以及任何其他由 def(...) 新引入的类型）进行进一步修改。
finalize();

// b.file 构建器函数现在可用。它期望两个参数，如上面 .build("name", "program") 所命名的。
const main = b.file("main.js", b.program([
  // 包含了无意义的程序内容以增加色彩。
  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");
// 等等。

// 如果你传递了错误类型的参数，或者未能传递足够的参数，将会抛出 AssertionError。

b.file(b.blockStatement([]));
// ==> AssertionError: {"body":[],"type":"BlockStatement","loc":null} 不匹配 string 类型

b.file("lib/types.js", b.thisExpression());
// ==> AssertionError: {"type":"ThisExpression","loc":null} 不匹配 Program 类型