—

              
package Data::Clone;
use 5.008_001;
use strict;
our $VERSION = '0.006';
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__
HideShow 184 lines of Pod
=head1 NAME
Data::Clone - Polymorphic data cloning
=head1 VERSION
This document describes Data::Clone version 0.006.
=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(Scalar) >>
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