README
1NAME
2 Clone::PP - Recursively copy Perl datatypes
3
4SYNOPSIS
5 use Clone::PP qw(clone);
6
7 $item = { 'foo' => 'bar', 'move' => [ 'zig', 'zag' ] };
8 $copy = clone( $item );
9
10 $item = [ 'alpha', 'beta', { 'gamma' => 'vlissides' } ];
11 $copy = clone( $item );
12
13 $item = Foo->new();
14 $copy = clone( $item );
15
16 Or as an object method:
17
18 require Clone::PP;
19 push @Foo::ISA, 'Clone::PP';
20
21 $item = Foo->new();
22 $copy = $item->clone();
23
24DESCRIPTION
25 This module provides a general-purpose clone function to make deep
26 copies of Perl data structures. It calls itself recursively to copy
27 nested hash, array, scalar and reference types, including tied variables
28 and objects.
29
30 The clone() function takes a scalar argument to copy. To duplicate
31 arrays or hashes, pass them in by reference:
32
33 my $copy = clone(\@array); my @copy = @{ clone(\@array) };
34 my $copy = clone(\%hash); my %copy = %{ clone(\%hash) };
35
36 The clone() function also accepts an optional second parameter that can
37 be used to limit the depth of the copy. If you pass a limit of 0, clone
38 will return the same value you supplied; for a limit of 1, a shallow
39 copy is constructed; for a limit of 2, two layers of copying are done,
40 and so on.
41
42 my $shallow_copy = clone( $item, 1 );
43
44 To allow objects to intervene in the way they are copied, the clone()
45 function checks for a couple of optional methods. If an object provides
46 a method named "clone_self", it is called and the result returned
47 without further processing. Alternately, if an object provides a method
48 named "clone_init", it is called on the copied object before it is
49 returned.
50
51BUGS
52 Some data types, such as globs, regexes, and code refs, are always
53 copied shallowly.
54
55 References to hash elements are not properly duplicated. (This is why
56 two tests in t/dclone.t that are marked "todo".) For example, the
57 following test should succeed but does not:
58
59 my $hash = { foo => 1 };
60 $hash->{bar} = \{ $hash->{foo} };
61 my $copy = clone( \%hash );
62 $hash->{foo} = 2;
63 $copy->{foo} = 2;
64 ok( $hash->{bar} == $copy->{bar} );
65
66 To report bugs via the CPAN web tracking system, go to
67 "http://rt.cpan.org/NoAuth/Bugs.html?Dist=Clone-PP" or send mail to
68 "Dist=Clone-PP#rt.cpan.org", replacing "#" with "@".
69
70SEE ALSO
71 For a faster implementation in XS, see the clone entry in the Clone
72 manpage, the clone entry in the Util manpage, or <Storable/dclone>.
73
74CREDITS AND COPYRIGHT
75 Developed by Matthew Simon Cavalletto at Evolution Softworks. More free
76 Perl software is available at "www.evoscript.org".
77
78 Copyright 2003 Matthew Simon Cavalletto. You may contact the author
79 directly at "evo@cpan.org" or "simonm@cavalletto.org".
80
81 Code initially derived from Ref.pm. Portions Copyright 1994 David Muir
82 Sharnoff.
83
84 Interface based by Clone by Ray Finch with contributions from
85 chocolateboy. Portions Copyright 2001 Ray Finch. Portions Copyright 2001
86 chocolateboy.
87
88 You may use, modify, and distribute this software under the same terms
89 as Perl.
90
91