1Data::Clone(3)        User Contributed Perl Documentation       Data::Clone(3)
2
3
4

NAME

6       Data::Clone - Polymorphic data cloning
7

VERSION

9       This document describes Data::Clone version 0.004.
10

SYNOPSIS

12           # as a function
13           use Data::Clone;
14
15           my $data   = YAML::Load("foo.yml"); # complex data structure
16           my $cloned = clone($data);
17
18           # makes Foo clonable
19           package Foo;
20           use Data::Clone;
21           # ...
22
23           # Foo is clonable
24           my $o = Foo->new();
25           my $c = clone($o); # $o is deeply copied
26
27           # used for custom clone methods
28           package Bar;
29           use Data::Clone qw(data_clone);
30           sub clone {
31               my($proto) = @_;
32               my $object = data_clone($proto);
33               $object->do_something();
34               return $object;
35           }
36           # ...
37
38           # Bar is also clonable
39           $o = Bar->new();
40           $c = clone($o); # Bar::clone() is called
41

DESCRIPTION

43       "Data::Clone" does data cloning, i.e. copies things recursively. This
44       is smart so that it works with not only non-blessed references, but
45       also with blessed references (i.e. objects). When clone() finds an
46       object, it calls a "clone" method of the object if the object has a
47       "clone", otherwise it makes a surface copy of the object. That is, this
48       module does polymorphic data cloning.
49
50       Although there are several modules on CPAN which can clone data, this
51       module has a different cloning policy from almost all of them.  See
52       "Cloning policy" and "Comparison to other cloning modules" for details.
53
54   Cloning policy
55       A cloning policy is a rule that how a cloning routine copies data. Here
56       is the cloning policy of "Data::Clone".
57
58       Non-reference values
59
60       Non-reference values are copied normally, which will drop their magics.
61
62       Scalar references
63
64       Scalar references including references to other types of references are
65       not copied deeply. They are copied on surface because it is typically
66       used to refer to something unique, namely global variables or magical
67       variables.
68
69       Array references
70
71       Array references are copied deeply. The cloning policy is applied to
72       each value recursively.
73
74       Hash references
75
76       Hash references are copied deeply. The cloning policy is applied to
77       each value recursively.
78
79       Glob, IO and Code references
80
81       These references are not copied deeply. They are copied on surface.
82
83       Blessed references (objects)
84
85       Blessed references are not copied deeply by default, because objects
86       might have external resources which "Data::Clone" could not deal with.
87       They will be copied deeply only if "Data::Clone" knows they are
88       clonable, i.e. they have a "clone" method.
89
90       If you want to make an object clonable, you can use the clone()
91       function as a method:
92
93           package Your::Class;
94           use Data::Clone;
95
96           # ...
97           my $your_class = Your::Class->new();
98
99           my $c = clone($your_object); # $your_object->clone() will be called
100
101       Or you can import data_clone() function to define your custom clone
102       method:
103
104           package Your::Class;
105           use Data::Clone qw(data_clone);
106
107           sub clone {
108               my($proto) = @_;
109               my $object = data_clone($proto);
110               # anything what you want
111               return $object;
112           }
113
114       Of course, you can use Clone::clone(), Storable::dclone(), and/or
115       anything you want as an implementation of "clone" methods.
116
117   Comparison to other cloning modules
118       There are modules which does data cloning.
119
120       "Storable" is a standard module which can clone data with dclone().  It
121       has a different cloning policy from "Data::Clone". By default it tries
122       to make a deep copy of all the data including blessed references, but
123       you can change its behaviour with specific hook methods.
124
125       "Clone" is a well-known cloning module, but it does not polymorphic
126       cloning. This makes a deep copy of data regardless of its types.
127       Moreover, there is no way to change its behaviour, so this is useful
128       only for data which link to no external resources.
129
130       "Data::Clone" makes a deep copy of data only if it knows that the data
131       are clonable. You can change its behaviour simply by defining "clone"
132       methods.  It also exceeds "Storable" and "Clone" in performance.
133

INTERFACE

135   Exported functions
136       clone(Scalar)
137
138       Returns a copy of Scalar.
139
140   Exportable functions
141       data_clone(Scalar)
142
143       Returns a copy of Scalar.
144
145       The same as clone(). Provided for custom clone methods.
146
147       is_cloning()
148
149       Returns true inside the clone() function, false otherwise.
150

DEPENDENCIES

152       Perl 5.8.1 or later, and a C compiler.
153

BUGS

155       No bugs have been reported.
156
157       Please report any bugs or feature requests to the author.
158

SEE ALSO

160       Storable
161
162       Clone
163

AUTHOR

165       Goro Fuji (gfx) <gfuji(at)cpan.org>
166

168       Copyright (c) 2010, Goro Fuji (gfx). All rights reserved.
169
170       This library is free software; you can redistribute it and/or modify it
171       under the same terms as Perl itself.
172
173
174
175perl v5.36.0                      2023-01-20                    Data::Clone(3)
Impressum