www.aleph1.co.uk Git - yaffs-website/blob - node_modules/gulp/node_modules/clone/README.md

   1 # clone
   2
   3 [![build status](https://secure.travis-ci.org/pvorb/node-clone.png)](http://travis-ci.org/pvorb/node-clone)
   4
   5 offers foolproof _deep cloning_ of variables in JavaScript.
   6
   7
   8 ## Installation
   9
  10     npm install clone
  11
  12 or
  13
  14     ender build clone
  15
  16
  17 ## Example
  18
  19 ~~~ javascript
  20 var clone = require('clone');
  21
  22 var a, b;
  23
  24 a = { foo: { bar: 'baz' } };  // initial value of a
  25
  26 b = clone(a);                 // clone a -> b
  27 a.foo.bar = 'foo';            // change a
  28
  29 console.log(a);               // show a
  30 console.log(b);               // show b
  31 ~~~
  32
  33 This will print:
  34
  35 ~~~ javascript
  36 { foo: { bar: 'foo' } }
  37 { foo: { bar: 'baz' } }
  38 ~~~
  39
  40 **clone** masters cloning simple objects (even with custom prototype), arrays,
  41 Date objects, and RegExp objects. Everything is cloned recursively, so that you
  42 can clone dates in arrays in objects, for example.
  43
  44
  45 ## API
  46
  47 `clone(val, circular, depth)`
  48
  49   * `val` -- the value that you want to clone, any type allowed
  50   * `circular` -- boolean
  51
  52     Call `clone` with `circular` set to `false` if you are certain that `obj`
  53     contains no circular references. This will give better performance if needed.
  54     There is no error if `undefined` or `null` is passed as `obj`.
  55   * `depth` -- depth to which the object is to be cloned (optional,
  56     defaults to infinity)
  57
  58 `clone.clonePrototype(obj)`
  59
  60   * `obj` -- the object that you want to clone
  61
  62 Does a prototype clone as
  63 [described by Oran Looney](http://oranlooney.com/functional-javascript/).
  64
  65
  66 ## Circular References
  67
  68 ~~~ javascript
  69 var a, b;
  70
  71 a = { hello: 'world' };
  72
  73 a.myself = a;
  74 b = clone(a);
  75
  76 console.log(b);
  77 ~~~
  78
  79 This will print:
  80
  81 ~~~ javascript
  82 { hello: "world", myself: [Circular] }
  83 ~~~
  84
  85 So, `b.myself` points to `b`, not `a`. Neat!
  86
  87
  88 ## Test
  89
  90     npm test
  91
  92
  93 ## Caveat
  94
  95 Some special objects like a socket or `process.stdout`/`stderr` are known to not
  96 be cloneable. If you find other objects that cannot be cloned, please [open an
  97 issue](https://github.com/pvorb/node-clone/issues/new).
  98
  99
 100 ## Bugs and Issues
 101
 102 If you encounter any bugs or issues, feel free to [open an issue at
 103 github](https://github.com/pvorb/node-clone/issues) or send me an email to
 104 <paul@vorba.ch>. I also always like to hear from you, if you’re using my code.
 105
 106 ## License
 107
 108 Copyright © 2011-2014 [Paul Vorbach](http://paul.vorba.ch/) and
 109 [contributors](https://github.com/pvorb/node-clone/graphs/contributors).
 110
 111 Permission is hereby granted, free of charge, to any person obtaining a copy of
 112 this software and associated documentation files (the “Software”), to deal in
 113 the Software without restriction, including without limitation the rights to
 114 use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
 115 the Software, and to permit persons to whom the Software is furnished to do so,
 116 subject to the following conditions:
 117
 118 The above copyright notice and this permission notice shall be included in all
 119 copies or substantial portions of the Software.
 120
 121 THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 122 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
 123 FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
 124 COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
 125 IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, OUT OF OR IN CONNECTION WITH THE
 126 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.