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