line |
stmt |
bran |
cond |
sub |
pod |
time |
code |
1
|
|
|
|
|
|
|
package Data::Clone; |
2
|
|
|
|
|
|
|
|
3
|
9
|
|
|
9
|
|
777791
|
use 5.008_001; |
|
9
|
|
|
|
|
43
|
|
|
9
|
|
|
|
|
366
|
|
4
|
9
|
|
|
9
|
|
55
|
use strict; |
|
9
|
|
|
|
|
17
|
|
|
9
|
|
|
|
|
489
|
|
5
|
|
|
|
|
|
|
|
6
|
|
|
|
|
|
|
our $VERSION = '0.004'; |
7
|
|
|
|
|
|
|
|
8
|
9
|
|
|
9
|
|
57
|
use XSLoader; |
|
9
|
|
|
|
|
22
|
|
|
9
|
|
|
|
|
391
|
|
9
|
|
|
|
|
|
|
XSLoader::load(__PACKAGE__, $VERSION); |
10
|
|
|
|
|
|
|
|
11
|
9
|
|
|
9
|
|
11562
|
use parent qw(Exporter); |
|
9
|
|
|
|
|
4265
|
|
|
9
|
|
|
|
|
50
|
|
12
|
|
|
|
|
|
|
our @EXPORT = qw(clone); |
13
|
|
|
|
|
|
|
our @EXPORT_OK = qw(data_clone TIECLONE); |
14
|
|
|
|
|
|
|
|
15
|
|
|
|
|
|
|
sub data_clone; |
16
|
|
|
|
|
|
|
*data_clone = \&clone; # alias |
17
|
|
|
|
|
|
|
|
18
|
|
|
|
|
|
|
sub TIECLONE; |
19
|
|
|
|
|
|
|
*TIECLONE = \&clone; # alias |
20
|
|
|
|
|
|
|
|
21
|
|
|
|
|
|
|
1; |
22
|
|
|
|
|
|
|
__END__ |
23
|
|
|
|
|
|
|
|
24
|
|
|
|
|
|
|
=head1 NAME |
25
|
|
|
|
|
|
|
|
26
|
|
|
|
|
|
|
Data::Clone - Polymorphic data cloning |
27
|
|
|
|
|
|
|
|
28
|
|
|
|
|
|
|
=head1 VERSION |
29
|
|
|
|
|
|
|
|
30
|
|
|
|
|
|
|
This document describes Data::Clone version 0.004. |
31
|
|
|
|
|
|
|
|
32
|
|
|
|
|
|
|
=head1 SYNOPSIS |
33
|
|
|
|
|
|
|
|
34
|
|
|
|
|
|
|
# as a function |
35
|
|
|
|
|
|
|
use Data::Clone; |
36
|
|
|
|
|
|
|
|
37
|
|
|
|
|
|
|
my $data = YAML::Load("foo.yml"); # complex data structure |
38
|
|
|
|
|
|
|
my $cloned = clone($data); |
39
|
|
|
|
|
|
|
|
40
|
|
|
|
|
|
|
# makes Foo clonable |
41
|
|
|
|
|
|
|
package Foo; |
42
|
|
|
|
|
|
|
use Data::Clone; |
43
|
|
|
|
|
|
|
# ... |
44
|
|
|
|
|
|
|
|
45
|
|
|
|
|
|
|
# Foo is clonable |
46
|
|
|
|
|
|
|
my $o = Foo->new(); |
47
|
|
|
|
|
|
|
my $c = clone($o); # $o is deeply copied |
48
|
|
|
|
|
|
|
|
49
|
|
|
|
|
|
|
# used for custom clone methods |
50
|
|
|
|
|
|
|
package Bar; |
51
|
|
|
|
|
|
|
use Data::Clone qw(data_clone); |
52
|
|
|
|
|
|
|
sub clone { |
53
|
|
|
|
|
|
|
my($proto) = @_; |
54
|
|
|
|
|
|
|
my $object = data_clone($proto); |
55
|
|
|
|
|
|
|
$object->do_something(); |
56
|
|
|
|
|
|
|
return $object; |
57
|
|
|
|
|
|
|
} |
58
|
|
|
|
|
|
|
# ... |
59
|
|
|
|
|
|
|
|
60
|
|
|
|
|
|
|
# Bar is also clonable |
61
|
|
|
|
|
|
|
$o = Bar->new(); |
62
|
|
|
|
|
|
|
$c = clone($o); # Bar::clone() is called |
63
|
|
|
|
|
|
|
|
64
|
|
|
|
|
|
|
=head1 DESCRIPTION |
65
|
|
|
|
|
|
|
|
66
|
|
|
|
|
|
|
C<Data::Clone> does data cloning, i.e. copies things recursively. This is |
67
|
|
|
|
|
|
|
smart so that it works with not only non-blessed references, but also with |
68
|
|
|
|
|
|
|
blessed references (i.e. objects). When C<clone()> finds an object, it |
69
|
|
|
|
|
|
|
calls a C<clone> method of the object if the object has a C<clone>, otherwise |
70
|
|
|
|
|
|
|
it makes a surface copy of the object. That is, this module does polymorphic |
71
|
|
|
|
|
|
|
data cloning. |
72
|
|
|
|
|
|
|
|
73
|
|
|
|
|
|
|
Although there are several modules on CPAN which can clone data, |
74
|
|
|
|
|
|
|
this module has a different cloning policy from almost all of them. |
75
|
|
|
|
|
|
|
See L</Cloning policy> and L</Comparison to other cloning modules> for |
76
|
|
|
|
|
|
|
details. |
77
|
|
|
|
|
|
|
|
78
|
|
|
|
|
|
|
=head2 Cloning policy |
79
|
|
|
|
|
|
|
|
80
|
|
|
|
|
|
|
A cloning policy is a rule that how a cloning routine copies data. Here is |
81
|
|
|
|
|
|
|
the cloning policy of C<Data::Clone>. |
82
|
|
|
|
|
|
|
|
83
|
|
|
|
|
|
|
=head3 Non-reference values |
84
|
|
|
|
|
|
|
|
85
|
|
|
|
|
|
|
Non-reference values are copied normally, which will drop their magics. |
86
|
|
|
|
|
|
|
|
87
|
|
|
|
|
|
|
=head3 Scalar references |
88
|
|
|
|
|
|
|
|
89
|
|
|
|
|
|
|
Scalar references including references to other types of references |
90
|
|
|
|
|
|
|
are B<not> copied deeply. They are copied on surface |
91
|
|
|
|
|
|
|
because it is typically used to refer to something unique, namely |
92
|
|
|
|
|
|
|
global variables or magical variables. |
93
|
|
|
|
|
|
|
|
94
|
|
|
|
|
|
|
=head3 Array references |
95
|
|
|
|
|
|
|
|
96
|
|
|
|
|
|
|
Array references are copied deeply. The cloning policy is applied to each |
97
|
|
|
|
|
|
|
value recursively. |
98
|
|
|
|
|
|
|
|
99
|
|
|
|
|
|
|
=head3 Hash references |
100
|
|
|
|
|
|
|
|
101
|
|
|
|
|
|
|
Hash references are copied deeply. The cloning policy is applied to each |
102
|
|
|
|
|
|
|
value recursively. |
103
|
|
|
|
|
|
|
|
104
|
|
|
|
|
|
|
=head3 Glob, IO and Code references |
105
|
|
|
|
|
|
|
|
106
|
|
|
|
|
|
|
These references are B<not> copied deeply. They are copied on surface. |
107
|
|
|
|
|
|
|
|
108
|
|
|
|
|
|
|
=head3 Blessed references (objects) |
109
|
|
|
|
|
|
|
|
110
|
|
|
|
|
|
|
Blessed references are B<not> copied deeply by default, because objects might |
111
|
|
|
|
|
|
|
have external resources which C<Data::Clone> could not deal with. |
112
|
|
|
|
|
|
|
They will be copied deeply only if C<Data::Clone> knows they are clonable, |
113
|
|
|
|
|
|
|
i.e. they have a C<clone> method. |
114
|
|
|
|
|
|
|
|
115
|
|
|
|
|
|
|
If you want to make an object clonable, you can use the C<clone()> function |
116
|
|
|
|
|
|
|
as a method: |
117
|
|
|
|
|
|
|
|
118
|
|
|
|
|
|
|
package Your::Class; |
119
|
|
|
|
|
|
|
use Data::Clone; |
120
|
|
|
|
|
|
|
|
121
|
|
|
|
|
|
|
# ... |
122
|
|
|
|
|
|
|
my $your_class = Your::Class->new(); |
123
|
|
|
|
|
|
|
|
124
|
|
|
|
|
|
|
my $c = clone($your_object); # $your_object->clone() will be called |
125
|
|
|
|
|
|
|
|
126
|
|
|
|
|
|
|
Or you can import C<data_clone()> function to define your custom clone method: |
127
|
|
|
|
|
|
|
|
128
|
|
|
|
|
|
|
package Your::Class; |
129
|
|
|
|
|
|
|
use Data::Clone qw(data_clone); |
130
|
|
|
|
|
|
|
|
131
|
|
|
|
|
|
|
sub clone { |
132
|
|
|
|
|
|
|
my($proto) = @_; |
133
|
|
|
|
|
|
|
my $object = data_clone($proto); |
134
|
|
|
|
|
|
|
# anything what you want |
135
|
|
|
|
|
|
|
return $object; |
136
|
|
|
|
|
|
|
} |
137
|
|
|
|
|
|
|
|
138
|
|
|
|
|
|
|
Of course, you can use C<Clone::clone()>, C<Storable::dclone()>, and/or |
139
|
|
|
|
|
|
|
anything you want as an implementation of C<clone> methods. |
140
|
|
|
|
|
|
|
|
141
|
|
|
|
|
|
|
=head2 Comparison to other cloning modules |
142
|
|
|
|
|
|
|
|
143
|
|
|
|
|
|
|
There are modules which does data cloning. |
144
|
|
|
|
|
|
|
|
145
|
|
|
|
|
|
|
C<Storable> is a standard module which can clone data with C<dclone()>. |
146
|
|
|
|
|
|
|
It has a different cloning policy from C<Data::Clone>. By default it tries |
147
|
|
|
|
|
|
|
to make a deep copy of all the data including blessed references, but you |
148
|
|
|
|
|
|
|
can change its behaviour with specific hook methods. |
149
|
|
|
|
|
|
|
|
150
|
|
|
|
|
|
|
C<Clone> is a well-known cloning module, but it does not polymorphic |
151
|
|
|
|
|
|
|
cloning. This makes a deep copy of data regardless of its types. Moreover, there |
152
|
|
|
|
|
|
|
is no way to change its behaviour, so this is useful only for data which |
153
|
|
|
|
|
|
|
link to no external resources. |
154
|
|
|
|
|
|
|
|
155
|
|
|
|
|
|
|
C<Data::Clone> makes a deep copy of data only if it knows that the data are |
156
|
|
|
|
|
|
|
clonable. You can change its behaviour simply by defining C<clone> methods. |
157
|
|
|
|
|
|
|
It also exceeds C<Storable> and C<Clone> in performance. |
158
|
|
|
|
|
|
|
|
159
|
|
|
|
|
|
|
=head1 INTERFACE |
160
|
|
|
|
|
|
|
|
161
|
|
|
|
|
|
|
=head2 Exported functions |
162
|
|
|
|
|
|
|
|
163
|
|
|
|
|
|
|
=head3 B<< clone(Scalar) >> |
164
|
|
|
|
|
|
|
|
165
|
|
|
|
|
|
|
Returns a copy of I<Scalar>. |
166
|
|
|
|
|
|
|
|
167
|
|
|
|
|
|
|
=head2 Exportable functions |
168
|
|
|
|
|
|
|
|
169
|
|
|
|
|
|
|
=head3 B<< data_clone(Scalar) >> |
170
|
|
|
|
|
|
|
|
171
|
|
|
|
|
|
|
Returns a copy of I<Scalar>. |
172
|
|
|
|
|
|
|
|
173
|
|
|
|
|
|
|
The same as C<clone()>. Provided for custom clone methods. |
174
|
|
|
|
|
|
|
|
175
|
|
|
|
|
|
|
=head3 B<< is_cloning() >> |
176
|
|
|
|
|
|
|
|
177
|
|
|
|
|
|
|
Returns true inside the C<clone()> function, false otherwise. |
178
|
|
|
|
|
|
|
|
179
|
|
|
|
|
|
|
=head1 DEPENDENCIES |
180
|
|
|
|
|
|
|
|
181
|
|
|
|
|
|
|
Perl 5.8.1 or later, and a C compiler. |
182
|
|
|
|
|
|
|
|
183
|
|
|
|
|
|
|
=head1 BUGS |
184
|
|
|
|
|
|
|
|
185
|
|
|
|
|
|
|
No bugs have been reported. |
186
|
|
|
|
|
|
|
|
187
|
|
|
|
|
|
|
Please report any bugs or feature requests to the author. |
188
|
|
|
|
|
|
|
|
189
|
|
|
|
|
|
|
=head1 SEE ALSO |
190
|
|
|
|
|
|
|
|
191
|
|
|
|
|
|
|
L<Storable> |
192
|
|
|
|
|
|
|
|
193
|
|
|
|
|
|
|
L<Clone> |
194
|
|
|
|
|
|
|
|
195
|
|
|
|
|
|
|
=head1 AUTHOR |
196
|
|
|
|
|
|
|
|
197
|
|
|
|
|
|
|
Goro Fuji (gfx) E<lt>gfuji(at)cpan.orgE<gt> |
198
|
|
|
|
|
|
|
|
199
|
|
|
|
|
|
|
=head1 LICENSE AND COPYRIGHT |
200
|
|
|
|
|
|
|
|
201
|
|
|
|
|
|
|
Copyright (c) 2010, Goro Fuji (gfx). All rights reserved. |
202
|
|
|
|
|
|
|
|
203
|
|
|
|
|
|
|
This library is free software; you can redistribute it and/or modify |
204
|
|
|
|
|
|
|
it under the same terms as Perl itself. |
205
|
|
|
|
|
|
|
|
206
|
|
|
|
|
|
|
=cut |