1 | traverse
|
2 | ========
|
3 |
|
4 | Traverse and transform objects by visiting every node on a recursive walk.
|
5 |
|
6 | examples
|
7 | ========
|
8 |
|
9 | transform negative numbers in-place
|
10 | -----------------------------------
|
11 |
|
12 | negative.js
|
13 |
|
14 | ````javascript
|
15 | var traverse = require('traverse');
|
16 | var obj = [ 5, 6, -3, [ 7, 8, -2, 1 ], { f : 10, g : -13 } ];
|
17 |
|
18 | traverse(obj).forEach(function (x) {
|
19 | if (x < 0) this.update(x + 128);
|
20 | });
|
21 |
|
22 | console.dir(obj);
|
23 | ````
|
24 |
|
25 | Output:
|
26 |
|
27 | [ 5, 6, 125, [ 7, 8, 126, 1 ], { f: 10, g: 115 } ]
|
28 |
|
29 | collect leaf nodes
|
30 | ------------------
|
31 |
|
32 | leaves.js
|
33 |
|
34 | ````javascript
|
35 | var traverse = require('traverse');
|
36 |
|
37 | var obj = {
|
38 | a : [1,2,3],
|
39 | b : 4,
|
40 | c : [5,6],
|
41 | d : { e : [7,8], f : 9 },
|
42 | };
|
43 |
|
44 | var leaves = traverse(obj).reduce(function (acc, x) {
|
45 | if (this.isLeaf) acc.push(x);
|
46 | return acc;
|
47 | }, []);
|
48 |
|
49 | console.dir(leaves);
|
50 | ````
|
51 |
|
52 | Output:
|
53 |
|
54 | [ 1, 2, 3, 4, 5, 6, 7, 8, 9 ]
|
55 |
|
56 | scrub circular references
|
57 | -------------------------
|
58 |
|
59 | scrub.js:
|
60 |
|
61 | ````javascript
|
62 | var traverse = require('traverse');
|
63 |
|
64 | var obj = { a : 1, b : 2, c : [ 3, 4 ] };
|
65 | obj.c.push(obj);
|
66 |
|
67 | var scrubbed = traverse(obj).map(function (x) {
|
68 | if (this.circular) this.remove()
|
69 | });
|
70 | console.dir(scrubbed);
|
71 | ````
|
72 |
|
73 | output:
|
74 |
|
75 | { a: 1, b: 2, c: [ 3, 4 ] }
|
76 |
|
77 | context
|
78 | =======
|
79 |
|
80 | Each method that takes a callback has a context (its `this` object) with these
|
81 | attributes:
|
82 |
|
83 | this.node
|
84 | ---------
|
85 |
|
86 | The present node on the recursive walk
|
87 |
|
88 | this.path
|
89 | ---------
|
90 |
|
91 | An array of string keys from the root to the present node
|
92 |
|
93 | this.parent
|
94 | -----------
|
95 |
|
96 | The context of the node's parent.
|
97 | This is `undefined` for the root node.
|
98 |
|
99 | this.key
|
100 | --------
|
101 |
|
102 | The name of the key of the present node in its parent.
|
103 | This is `undefined` for the root node.
|
104 |
|
105 | this.isRoot, this.notRoot
|
106 | -------------------------
|
107 |
|
108 | Whether the present node is the root node
|
109 |
|
110 | this.isLeaf, this.notLeaf
|
111 | -------------------------
|
112 |
|
113 | Whether or not the present node is a leaf node (has no children)
|
114 |
|
115 | this.level
|
116 | ----------
|
117 |
|
118 | Depth of the node within the traversal
|
119 |
|
120 | this.circular
|
121 | -------------
|
122 |
|
123 | If the node equals one of its parents, the `circular` attribute is set to the
|
124 | context of that parent and the traversal progresses no deeper.
|
125 |
|
126 | this.update(value, stopHere=false)
|
127 | ----------------------------------
|
128 |
|
129 | Set a new value for the present node.
|
130 |
|
131 | All the elements in `value` will be recursively traversed unless `stopHere` is
|
132 | true.
|
133 |
|
134 | this.remove(stopHere=false)
|
135 | -------------
|
136 |
|
137 | Remove the current element from the output. If the node is in an Array it will
|
138 | be spliced off. Otherwise it will be deleted from its parent.
|
139 |
|
140 | this.delete(stopHere=false)
|
141 | -------------
|
142 |
|
143 | Delete the current element from its parent in the output. Calls `delete` even on
|
144 | Arrays.
|
145 |
|
146 | this.before(fn)
|
147 | ---------------
|
148 |
|
149 | Call this function before any of the children are traversed.
|
150 |
|
151 | You can assign into `this.keys` here to traverse in a custom order.
|
152 |
|
153 | this.after(fn)
|
154 | --------------
|
155 |
|
156 | Call this function after any of the children are traversed.
|
157 |
|
158 | this.pre(fn)
|
159 | ------------
|
160 |
|
161 | Call this function before each of the children are traversed.
|
162 |
|
163 | this.post(fn)
|
164 | -------------
|
165 |
|
166 | Call this function after each of the children are traversed.
|
167 |
|
168 | methods
|
169 | =======
|
170 |
|
171 | .map(fn)
|
172 | --------
|
173 |
|
174 | Execute `fn` for each node in the object and return a new object with the
|
175 | results of the walk. To update nodes in the result use `this.update(value)`.
|
176 |
|
177 | .forEach(fn)
|
178 | ------------
|
179 |
|
180 | Execute `fn` for each node in the object but unlike `.map()`, when
|
181 | `this.update()` is called it updates the object in-place.
|
182 |
|
183 | .reduce(fn, acc)
|
184 | ----------------
|
185 |
|
186 | For each node in the object, perform a
|
187 | [left-fold](http://en.wikipedia.org/wiki/Fold_(higher-order_function))
|
188 | with the return value of `fn(acc, node)`.
|
189 |
|
190 | If `acc` isn't specified, `acc` is set to the root object for the first step
|
191 | and the root element is skipped.
|
192 |
|
193 | .paths()
|
194 | --------
|
195 |
|
196 | Return an `Array` of every possible non-cyclic path in the object.
|
197 | Paths are `Array`s of string keys.
|
198 |
|
199 | .nodes()
|
200 | --------
|
201 |
|
202 | Return an `Array` of every node in the object.
|
203 |
|
204 | .clone()
|
205 | --------
|
206 |
|
207 | Create a deep clone of the object.
|
208 |
|
209 | install
|
210 | =======
|
211 |
|
212 | Using [npm](http://npmjs.org) do:
|
213 |
|
214 | $ npm install traverse
|
215 |
|
216 | test
|
217 | ====
|
218 |
|
219 | Using [expresso](http://github.com/visionmedia/expresso) do:
|
220 |
|
221 | $ expresso
|
222 |
|
223 | 100% wahoo, your stuff is not broken!
|
224 |
|
225 | in the browser
|
226 | ==============
|
227 |
|
228 | Use [browserify](https://github.com/substack/node-browserify) to run traverse in
|
229 | the browser.
|
230 |
|
231 | traverse has been tested and works with:
|
232 |
|
233 | * Internet Explorer 5.5, 6.0, 7.0, 8.0, 9.0
|
234 | * Firefox 3.5
|
235 | * Chrome 6.0
|
236 | * Opera 10.6
|
237 | * Safari 5.0
|
238 |
|
\ | No newline at end of file |