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 | methods
|
78 | =======
|
79 |
|
80 | Each method that takes an `fn` uses the context documented below in the context
|
81 | section.
|
82 |
|
83 | .map(fn)
|
84 | --------
|
85 |
|
86 | Execute `fn` for each node in the object and return a new object with the
|
87 | results of the walk. To update nodes in the result use `this.update(value)`.
|
88 |
|
89 | .forEach(fn)
|
90 | ------------
|
91 |
|
92 | Execute `fn` for each node in the object but unlike `.map()`, when
|
93 | `this.update()` is called it updates the object in-place.
|
94 |
|
95 | .reduce(fn, acc)
|
96 | ----------------
|
97 |
|
98 | For each node in the object, perform a
|
99 | [left-fold](http://en.wikipedia.org/wiki/Fold_(higher-order_function))
|
100 | with the return value of `fn(acc, node)`.
|
101 |
|
102 | If `acc` isn't specified, `acc` is set to the root object for the first step
|
103 | and the root element is skipped.
|
104 |
|
105 | .paths()
|
106 | --------
|
107 |
|
108 | Return an `Array` of every possible non-cyclic path in the object.
|
109 | Paths are `Array`s of string keys.
|
110 |
|
111 | .nodes()
|
112 | --------
|
113 |
|
114 | Return an `Array` of every node in the object.
|
115 |
|
116 | .clone()
|
117 | --------
|
118 |
|
119 | Create a deep clone of the object.
|
120 |
|
121 | .get(path)
|
122 | ----------
|
123 |
|
124 | Get the element at the array `path`.
|
125 |
|
126 | .set(path, value)
|
127 | -----------------
|
128 |
|
129 | Set the element at the array `path` to `value`.
|
130 |
|
131 | .has(path)
|
132 | ----------
|
133 |
|
134 | Return whether the element at the array `path` exists.
|
135 |
|
136 | context
|
137 | =======
|
138 |
|
139 | Each method that takes a callback has a context (its `this` object) with these
|
140 | attributes:
|
141 |
|
142 | this.node
|
143 | ---------
|
144 |
|
145 | The present node on the recursive walk
|
146 |
|
147 | this.path
|
148 | ---------
|
149 |
|
150 | An array of string keys from the root to the present node
|
151 |
|
152 | this.parent
|
153 | -----------
|
154 |
|
155 | The context of the node's parent.
|
156 | This is `undefined` for the root node.
|
157 |
|
158 | this.key
|
159 | --------
|
160 |
|
161 | The name of the key of the present node in its parent.
|
162 | This is `undefined` for the root node.
|
163 |
|
164 | this.isRoot, this.notRoot
|
165 | -------------------------
|
166 |
|
167 | Whether the present node is the root node
|
168 |
|
169 | this.isLeaf, this.notLeaf
|
170 | -------------------------
|
171 |
|
172 | Whether or not the present node is a leaf node (has no children)
|
173 |
|
174 | this.level
|
175 | ----------
|
176 |
|
177 | Depth of the node within the traversal
|
178 |
|
179 | this.circular
|
180 | -------------
|
181 |
|
182 | If the node equals one of its parents, the `circular` attribute is set to the
|
183 | context of that parent and the traversal progresses no deeper.
|
184 |
|
185 | this.update(value, stopHere=false)
|
186 | ----------------------------------
|
187 |
|
188 | Set a new value for the present node.
|
189 |
|
190 | All the elements in `value` will be recursively traversed unless `stopHere` is
|
191 | true.
|
192 |
|
193 | this.remove(stopHere=false)
|
194 | -------------
|
195 |
|
196 | Remove the current element from the output. If the node is in an Array it will
|
197 | be spliced off. Otherwise it will be deleted from its parent.
|
198 |
|
199 | this.delete(stopHere=false)
|
200 | -------------
|
201 |
|
202 | Delete the current element from its parent in the output. Calls `delete` even on
|
203 | Arrays.
|
204 |
|
205 | this.before(fn)
|
206 | ---------------
|
207 |
|
208 | Call this function before any of the children are traversed.
|
209 |
|
210 | You can assign into `this.keys` here to traverse in a custom order.
|
211 |
|
212 | this.after(fn)
|
213 | --------------
|
214 |
|
215 | Call this function after any of the children are traversed.
|
216 |
|
217 | this.pre(fn)
|
218 | ------------
|
219 |
|
220 | Call this function before each of the children are traversed.
|
221 |
|
222 | this.post(fn)
|
223 | -------------
|
224 |
|
225 | Call this function after each of the children are traversed.
|
226 |
|
227 |
|
228 | install
|
229 | =======
|
230 |
|
231 | Using [npm](http://npmjs.org) do:
|
232 |
|
233 | $ npm install traverse
|
234 |
|
235 | test
|
236 | ====
|
237 |
|
238 | Using [expresso](http://github.com/visionmedia/expresso) do:
|
239 |
|
240 | $ expresso
|
241 |
|
242 | 100% wahoo, your stuff is not broken!
|
243 |
|
244 | in the browser
|
245 | ==============
|
246 |
|
247 | Use [browserify](https://github.com/substack/node-browserify) to run traverse in
|
248 | the browser.
|
249 |
|
250 | traverse has been tested and works with:
|
251 |
|
252 | * Internet Explorer 5.5, 6.0, 7.0, 8.0, 9.0
|
253 | * Firefox 3.5
|
254 | * Chrome 6.0
|
255 | * Opera 10.6
|
256 | * Safari 5.0
|
257 |
|
\ | No newline at end of file |