libs/js/jquery-mobile-1.2.0/node_modules/grunt/node_modules/nodeunit/node_modules/tap/node_modules/difflet/node_modules/traverse/README.markdown

   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