You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

126 lines
4.4 KiB

  1. # Acorn AST walker
  2. An abstract syntax tree walker for the
  3. [ESTree](https://github.com/estree/estree) format.
  4. ## Community
  5. Acorn is open source software released under an
  6. [MIT license](https://github.com/acornjs/acorn/blob/master/acorn-walk/LICENSE).
  7. You are welcome to
  8. [report bugs](https://github.com/acornjs/acorn/issues) or create pull
  9. requests on [github](https://github.com/acornjs/acorn). For questions
  10. and discussion, please use the
  11. [Tern discussion forum](https://discuss.ternjs.net).
  12. ## Installation
  13. The easiest way to install acorn is from [`npm`](https://www.npmjs.com/):
  14. ```sh
  15. npm install acorn-walk
  16. ```
  17. Alternately, you can download the source and build acorn yourself:
  18. ```sh
  19. git clone https://github.com/acornjs/acorn.git
  20. cd acorn
  21. npm install
  22. ```
  23. ## Interface
  24. An algorithm for recursing through a syntax tree is stored as an
  25. object, with a property for each tree node type holding a function
  26. that will recurse through such a node. There are several ways to run
  27. such a walker.
  28. **simple**`(node, visitors, base, state)` does a 'simple' walk over a
  29. tree. `node` should be the AST node to walk, and `visitors` an object
  30. with properties whose names correspond to node types in the [ESTree
  31. spec](https://github.com/estree/estree). The properties should contain
  32. functions that will be called with the node object and, if applicable
  33. the state at that point. The last two arguments are optional. `base`
  34. is a walker algorithm, and `state` is a start state. The default
  35. walker will simply visit all statements and expressions and not
  36. produce a meaningful state. (An example of a use of state is to track
  37. scope at each point in the tree.)
  38. ```js
  39. const acorn = require("acorn")
  40. const walk = require("acorn-walk")
  41. walk.simple(acorn.parse("let x = 10"), {
  42. Literal(node) {
  43. console.log(`Found a literal: ${node.value}`)
  44. }
  45. })
  46. ```
  47. **ancestor**`(node, visitors, base, state)` does a 'simple' walk over
  48. a tree, building up an array of ancestor nodes (including the current node)
  49. and passing the array to the callbacks as a third parameter.
  50. ```js
  51. const acorn = require("acorn")
  52. const walk = require("acorn-walk")
  53. walk.ancestor(acorn.parse("foo('hi')"), {
  54. Literal(_, ancestors) {
  55. console.log("This literal's ancestors are:", ancestors.map(n => n.type))
  56. }
  57. })
  58. ```
  59. **recursive**`(node, state, functions, base)` does a 'recursive'
  60. walk, where the walker functions are responsible for continuing the
  61. walk on the child nodes of their target node. `state` is the start
  62. state, and `functions` should contain an object that maps node types
  63. to walker functions. Such functions are called with `(node, state, c)`
  64. arguments, and can cause the walk to continue on a sub-node by calling
  65. the `c` argument on it with `(node, state)` arguments. The optional
  66. `base` argument provides the fallback walker functions for node types
  67. that aren't handled in the `functions` object. If not given, the
  68. default walkers will be used.
  69. **make**`(functions, base)` builds a new walker object by using the
  70. walker functions in `functions` and filling in the missing ones by
  71. taking defaults from `base`.
  72. **full**`(node, callback, base, state)` does a 'full' walk over a
  73. tree, calling the callback with the arguments (node, state, type) for
  74. each node
  75. **fullAncestor**`(node, callback, base, state)` does a 'full' walk
  76. over a tree, building up an array of ancestor nodes (including the
  77. current node) and passing the array to the callbacks as a third
  78. parameter.
  79. ```js
  80. const acorn = require("acorn")
  81. const walk = require("acorn-walk")
  82. walk.full(acorn.parse("1 + 1"), node => {
  83. console.log(`There's a ${node.type} node at ${node.ch}`)
  84. })
  85. ```
  86. **findNodeAt**`(node, start, end, test, base, state)` tries to locate
  87. a node in a tree at the given start and/or end offsets, which
  88. satisfies the predicate `test`. `start` and `end` can be either `null`
  89. (as wildcard) or a number. `test` may be a string (indicating a node
  90. type) or a function that takes `(nodeType, node)` arguments and
  91. returns a boolean indicating whether this node is interesting. `base`
  92. and `state` are optional, and can be used to specify a custom walker.
  93. Nodes are tested from inner to outer, so if two nodes match the
  94. boundaries, the inner one will be preferred.
  95. **findNodeAround**`(node, pos, test, base, state)` is a lot like
  96. `findNodeAt`, but will match any node that exists 'around' (spanning)
  97. the given position.
  98. **findNodeAfter**`(node, pos, test, base, state)` is similar to
  99. `findNodeAround`, but will match all nodes *after* the given position
  100. (testing outer nodes before inner nodes).