.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Data::Clone 3pm"
.TH Data::Clone 3pm "2018-11-02" "perl v5.28.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Data::Clone \- Polymorphic data cloning
.SH "VERSION"
.IX Header "VERSION"
This document describes Data::Clone version 0.004.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    # 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
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`Data::Clone\*(C'\fR 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 \f(CW\*(C`clone()\*(C'\fR finds an object, it
calls a \f(CW\*(C`clone\*(C'\fR method of the object if the object has a \f(CW\*(C`clone\*(C'\fR, otherwise
it makes a surface copy of the object. That is, this module does polymorphic
data cloning.
.PP
Although there are several modules on \s-1CPAN\s0 which can clone data,
this module has a different cloning policy from almost all of them.
See \*(L"Cloning policy\*(R" and \*(L"Comparison to other cloning modules\*(R" for
details.
.SS "Cloning policy"
.IX Subsection "Cloning policy"
A cloning policy is a rule that how a cloning routine copies data. Here is
the cloning policy of \f(CW\*(C`Data::Clone\*(C'\fR.
.PP
\fINon-reference values\fR
.IX Subsection "Non-reference values"
.PP
Non-reference values are copied normally, which will drop their magics.
.PP
\fIScalar references\fR
.IX Subsection "Scalar references"
.PP
Scalar references including references to other types of references
are \fBnot\fR copied deeply. They are copied on surface
because it is typically used to refer to something unique, namely
global variables or magical variables.
.PP
\fIArray references\fR
.IX Subsection "Array references"
.PP
Array references are copied deeply. The cloning policy is applied to each
value recursively.
.PP
\fIHash references\fR
.IX Subsection "Hash references"
.PP
Hash references are copied deeply. The cloning policy is applied to each
value recursively.
.PP
\fIGlob, \s-1IO\s0 and Code references\fR
.IX Subsection "Glob, IO and Code references"
.PP
These references are \fBnot\fR copied deeply. They are copied on surface.
.PP
\fIBlessed references (objects)\fR
.IX Subsection "Blessed references (objects)"
.PP
Blessed references are \fBnot\fR copied deeply by default, because objects might
have external resources which \f(CW\*(C`Data::Clone\*(C'\fR could not deal with.
They will be copied deeply only if \f(CW\*(C`Data::Clone\*(C'\fR knows they are clonable,
i.e. they have a \f(CW\*(C`clone\*(C'\fR method.
.PP
If you want to make an object clonable, you can use the \f(CW\*(C`clone()\*(C'\fR function
as a method:
.PP
.Vb 2
\&    package Your::Class;
\&    use Data::Clone;
\&
\&    # ...
\&    my $your_class = Your::Class\->new();
\&
\&    my $c = clone($your_object); # $your_object\->clone() will be called
.Ve
.PP
Or you can import \f(CW\*(C`data_clone()\*(C'\fR function to define your custom clone method:
.PP
.Vb 2
\&    package Your::Class;
\&    use Data::Clone qw(data_clone);
\&
\&    sub clone {
\&        my($proto) = @_;
\&        my $object = data_clone($proto);
\&        # anything what you want
\&        return $object;
\&    }
.Ve
.PP
Of course, you can use \f(CW\*(C`Clone::clone()\*(C'\fR, \f(CW\*(C`Storable::dclone()\*(C'\fR, and/or
anything you want as an implementation of \f(CW\*(C`clone\*(C'\fR methods.
.SS "Comparison to other cloning modules"
.IX Subsection "Comparison to other cloning modules"
There are modules which does data cloning.
.PP
\&\f(CW\*(C`Storable\*(C'\fR is a standard module which can clone data with \f(CW\*(C`dclone()\*(C'\fR.
It has a different cloning policy from \f(CW\*(C`Data::Clone\*(C'\fR. 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.
.PP
\&\f(CW\*(C`Clone\*(C'\fR 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.
.PP
\&\f(CW\*(C`Data::Clone\*(C'\fR makes a deep copy of data only if it knows that the data are
clonable. You can change its behaviour simply by defining \f(CW\*(C`clone\*(C'\fR methods.
It also exceeds \f(CW\*(C`Storable\*(C'\fR and \f(CW\*(C`Clone\*(C'\fR in performance.
.SH "INTERFACE"
.IX Header "INTERFACE"
.SS "Exported functions"
.IX Subsection "Exported functions"
\fI\f(BIclone(Scalar)\fI\fR
.IX Subsection "clone(Scalar)"
.PP
Returns a copy of \fIScalar\fR.
.SS "Exportable functions"
.IX Subsection "Exportable functions"
\fI\f(BIdata_clone(Scalar)\fI\fR
.IX Subsection "data_clone(Scalar)"
.PP
Returns a copy of \fIScalar\fR.
.PP
The same as \f(CW\*(C`clone()\*(C'\fR. Provided for custom clone methods.
.PP
\fI\f(BI\f(BIis_cloning()\f(BI\fI\fR
.IX Subsection "is_cloning()"
.PP
Returns true inside the \f(CW\*(C`clone()\*(C'\fR function, false otherwise.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
Perl 5.8.1 or later, and a C compiler.
.SH "BUGS"
.IX Header "BUGS"
No bugs have been reported.
.PP
Please report any bugs or feature requests to the author.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Storable
.PP
Clone
.SH "AUTHOR"
.IX Header "AUTHOR"
Goro Fuji (gfx) <gfuji(at)cpan.org>
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
Copyright (c) 2010, Goro Fuji (gfx). All rights reserved.
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.