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.
|