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