Data::Clone(3pm)

👑 Data::Clone — the polymorphic data cloning bestie 💖

okay so welcome to Data::Clone, a Perl module that does polymorphic data cloning, and yes we're gonna make that phrase make sense, bestie. it lives in the User Contributed Perl Documentation section of the manual, and it's here to copy your stuff — recursively, intelligently, and with main character energy ✨

---

📖 NAME

Data::Clone — polymorphic data cloning 🦋

---

🔢 VERSION

this doc is describing Data::Clone version 0.006. periodt 💅

---

✨ 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

---

🌸 DESCRIPTION

Data::Clone does data cloning, which is the fancy way of saying it copies things recursively. but here's the glow-up: it's smart about it. it works not just with plain non-blessed references, but with blessed references too — aka objects. when clone() bumps into an object, it calls the object's "clone" method if there is one; if there isn't, it does a surface copy of the object instead. so basically, this module does polymorphic data cloning and it ate, no cap.

now, yes, there are other modules on CPAN that clone data. but this one has a totally different cloning policy from, like, almost all of them. the deets live in "Cloning policy" and "Comparison to other cloning modules" — go read those, bestie 🫶

🧠 Cloning policy

a cloning policy is just the rule for how a cloning routine copies data. here's Data::Clone's policy, item by item:

Non-reference values

non-reference values get copied normally, which will drop their magics. iykyk 💫

Scalar references

scalar references — including references to other types of references — are NOT copied deeply. they get copied on the surface, because typically you're using them to refer to something unique, like global variables or magical variables. so leave them alone, they're fine 💅

Array references

array references are copied deeply. the cloning policy gets applied to each value recursively. yes, all of them, down the whole tree 🌈

Hash references

hash references are also copied deeply. the cloning policy gets applied to each value recursively. same energy 🍓

Glob, IO and Code references

these references are not copied deeply. they're copied on the surface. that's it, that's the rule 🦋

Blessed references (objects)

blessed references are NOT copied deeply by default, because objects might have external resources that Data::Clone literally could not deal with. they only get copied deeply if Data::Clone knows they're clonable — meaning they have a "clone" method. 👑

so if you wanna make an object clonable, you can use the 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 the data_clone() function and define your own 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;
}

and of course, you can use Clone::clone(), Storable::dclone(), and/or honestly anything you want as the implementation of your "clone" methods. your clone method, your rules 💖

⚖️ Comparison to other cloning modules

there are other modules that do data cloning. let's do a little vibe check:

"Storable" is a standard module that can clone data with dclone(). it has a different cloning policy from Data::Clone. by default it tries to make a deep copy of all the data, blessed references included, but you can change its behaviour with specific hook methods.

"Clone" is a well-known cloning module, but it does not do polymorphic cloning. it makes a deep copy of data regardless of its types. and worse — there's no way to change its behaviour, so it's really only useful for data that links to no external resources 😭

Data::Clone, on the other hand, makes a deep copy of data only if it knows the data are clonable. and you can change its behaviour simply by defining "clone" methods. bonus: it also exceeds "Storable" and "Clone" in performance. ate and left no crumbs 🔥

---

🔌 INTERFACE

📦 Exported functions

• clone(Scalar) — returns a copy of Scalar. that's the whole job, and it does it slayfully ✨

🎁 Exportable functions

• data_clone(Scalar) — returns a copy of Scalar. it's the same as clone(). it's provided for custom clone methods, so you can build your own little clone situation 🎀
• is_cloning() — returns true inside the clone() function, and false otherwise. a tiny little vibe check for whether you're mid-clone 🦋

---

🧩 DEPENDENCIES

Perl 5.8.1 or later, and a C compiler. yeah bestie, there's C in here, bring your compiler 💀

---

🐛 BUGS

no bugs have been reported. iconic behaviour honestly 🙈

if you do find any, or you have feature requests, please report any bugs or feature requests to the author 🫶

---

👀 SEE ALSO

• Storable
• Clone

---

💜 AUTHOR

Goro Fuji (gfx) <gfuji(at)cpan.org> — thank you king 👑

---

📜 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.

---

and that's the whole page, bestie 💖 this little bundle of joy came to you via perl v5.42.3, dated 2026-08-20, filed under Data::Clone(3pm). go clone something safely, and remember: surface copy is still a copy, it's just not a deep one ✨🦋💅