1 | ### Estraverse [![Build Status](https://secure.travis-ci.org/estools/estraverse.svg)](http://travis-ci.org/estools/estraverse)
|
2 |
|
3 | Estraverse ([estraverse](http://github.com/estools/estraverse)) is
|
4 | [ECMAScript](http://www.ecma-international.org/publications/standards/Ecma-262.htm)
|
5 | traversal functions from [esmangle project](http://github.com/estools/esmangle).
|
6 |
|
7 | ### Documentation
|
8 |
|
9 | You can find usage docs at [wiki page](https://github.com/estools/estraverse/wiki/Usage).
|
10 |
|
11 | ### Example Usage
|
12 |
|
13 | The following code will output all variables declared at the root of a file.
|
14 |
|
15 | ```javascript
|
16 | estraverse.traverse(ast, {
|
17 | enter: function (node, parent) {
|
18 | if (node.type == 'FunctionExpression' || node.type == 'FunctionDeclaration')
|
19 | return estraverse.VisitorOption.Skip;
|
20 | },
|
21 | leave: function (node, parent) {
|
22 | if (node.type == 'VariableDeclarator')
|
23 | console.log(node.id.name);
|
24 | }
|
25 | });
|
26 | ```
|
27 |
|
28 | We can use `this.skip`, `this.remove` and `this.break` functions instead of using Skip, Remove and Break.
|
29 |
|
30 | ```javascript
|
31 | estraverse.traverse(ast, {
|
32 | enter: function (node) {
|
33 | this.break();
|
34 | }
|
35 | });
|
36 | ```
|
37 |
|
38 | And estraverse provides `estraverse.replace` function. When returning node from `enter`/`leave`, current node is replaced with it.
|
39 |
|
40 | ```javascript
|
41 | result = estraverse.replace(tree, {
|
42 | enter: function (node) {
|
43 | // Replace it with replaced.
|
44 | if (node.type === 'Literal')
|
45 | return replaced;
|
46 | }
|
47 | });
|
48 | ```
|
49 |
|
50 | By passing `visitor.keys` mapping, we can extend estraverse traversing functionality.
|
51 |
|
52 | ```javascript
|
53 | // This tree contains a user-defined `TestExpression` node.
|
54 | var tree = {
|
55 | type: 'TestExpression',
|
56 |
|
57 | // This 'argument' is the property containing the other **node**.
|
58 | argument: {
|
59 | type: 'Literal',
|
60 | value: 20
|
61 | },
|
62 |
|
63 | // This 'extended' is the property not containing the other **node**.
|
64 | extended: true
|
65 | };
|
66 | estraverse.traverse(tree, {
|
67 | enter: function (node) { },
|
68 |
|
69 | // Extending the existing traversing rules.
|
70 | keys: {
|
71 | // TargetNodeName: [ 'keys', 'containing', 'the', 'other', '**node**' ]
|
72 | TestExpression: ['argument']
|
73 | }
|
74 | });
|
75 | ```
|
76 |
|
77 | By passing `visitor.fallback` option, we can control the behavior when encountering unknown nodes.
|
78 |
|
79 | ```javascript
|
80 | // This tree contains a user-defined `TestExpression` node.
|
81 | var tree = {
|
82 | type: 'TestExpression',
|
83 |
|
84 | // This 'argument' is the property containing the other **node**.
|
85 | argument: {
|
86 | type: 'Literal',
|
87 | value: 20
|
88 | },
|
89 |
|
90 | // This 'extended' is the property not containing the other **node**.
|
91 | extended: true
|
92 | };
|
93 | estraverse.traverse(tree, {
|
94 | enter: function (node) { },
|
95 |
|
96 | // Iterating the child **nodes** of unknown nodes.
|
97 | fallback: 'iteration'
|
98 | });
|
99 | ```
|
100 |
|
101 | When `visitor.fallback` is a function, we can determine which keys to visit on each node.
|
102 |
|
103 | ```javascript
|
104 | // This tree contains a user-defined `TestExpression` node.
|
105 | var tree = {
|
106 | type: 'TestExpression',
|
107 |
|
108 | // This 'argument' is the property containing the other **node**.
|
109 | argument: {
|
110 | type: 'Literal',
|
111 | value: 20
|
112 | },
|
113 |
|
114 | // This 'extended' is the property not containing the other **node**.
|
115 | extended: true
|
116 | };
|
117 | estraverse.traverse(tree, {
|
118 | enter: function (node) { },
|
119 |
|
120 | // Skip the `argument` property of each node
|
121 | fallback: function(node) {
|
122 | return Object.keys(node).filter(function(key) {
|
123 | return key !== 'argument';
|
124 | });
|
125 | }
|
126 | });
|
127 | ```
|
128 |
|
129 | ### License
|
130 |
|
131 | Copyright (C) 2012-2016 [Yusuke Suzuki](http://github.com/Constellation)
|
132 | (twitter: [@Constellation](http://twitter.com/Constellation)) and other contributors.
|
133 |
|
134 | Redistribution and use in source and binary forms, with or without
|
135 | modification, are permitted provided that the following conditions are met:
|
136 |
|
137 | * Redistributions of source code must retain the above copyright
|
138 | notice, this list of conditions and the following disclaimer.
|
139 |
|
140 | * Redistributions in binary form must reproduce the above copyright
|
141 | notice, this list of conditions and the following disclaimer in the
|
142 | documentation and/or other materials provided with the distribution.
|
143 |
|
144 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
145 | AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
146 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
147 | ARE DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
|
148 | DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
149 | (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
150 | LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
|
151 | ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
152 | (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
|
153 | THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|