Class::Cloneable - A base class for Cloneable objects.
package MyObject; our @ISA = ('Class::Cloneable'); # calling clone on an instance of MyObject # will give you full deep-cloning functionality
This module provides a flexible base class for building objects with cloning capabilities. This module does it's best to respect the encapsulation of all other objects, including subclasses of itself. This is intended to be a stricter and more OO-ish option than the more general purpose Clone and Clone::PP modules.
This provided method will deep copy itself and return the clone, while respecting the encapsulation of any objects contained within itself.
For the most part, this will just "do the right thing" and can be used as-is. If however, you need a more specialized approach, see the section below for details on how you can override and customize this methods functionality.
Class::Cloneable::Util is a protected inner package, meaning that it can only be used by Class::Cloneable or it's subclasses. If an attempt is made to use it outside of that context, an exception is thrown.
This inner package is provided as a means of performing fine grained custom cloning operations for users who choose to or need to override the clone method provided by Class::Cloneable. Here is a basic example:
clone
package MyMoreComplexObject; our @ISA = ('Class::Cloneable'); sub clone { my ($self) = @_; my $clone = {}; $clone->{dont_clone_this} = $self->{dont_clone_this}; $clone->{clone_this} = Class::Cloneable::Util::clone($self->{clone_this}); return bless $clone, ref($self); }
NOTE: Many of the functions provided in this package require a $cache argument, which is a HASH reference that is used internally to keep track of the items already cloned to avoid cloning any circular references more than once. The only function here which does not require a $cache argument is the clone function, which will initialize its own $cache if one is not present.
$cache
For most custom cloning, just calling this function will be enough. The argument $to_clone is required, but the $cache argument can be omitted. This is only allowed in this function, all other functions in this package require that the $cache argument is a HASH reference.
$to_clone
This function will attempt to clone the $to_clone argument following these guidelines:
Then it is assumed that you are requested a "root" level cloning and the Class::Cloneable object is deconstructed and its internals are cloned. This results in a deep copy of the object in $to_clone, which will recursively call this Class::Cloneable::Util::clone function for each internal element.
Class::Cloneable::Util::clone
This is not considered a "root" level cloning so the clone method is called on the $to_clone object. By doing this, we respect the encapsulation of the Class::Cloneable subclass, in case it's clone method has been overridden with custom behavior.
This will call the clone method found and assume the value returned is a proper clone of the value in $to_clone.
We assume that because there is no clone method available to the object found stored in $to_clone, that the object does not want to be cloned. The idea is that we should respect the encapsulation of the object and not try to copy it's internals without it's permission.
We will deep copy the reference value in $to_clone, which will result in recursive calls to the Class::Cloneable::Util::clone function for all the internal values found inside $to_clone. This will also properly clone any tied references, being sure to tie the clones as well.
tied
tie
It is important to note that any CODE, RegExp and GLOB references are not copied, only passed through. Short of some really insane perl code, this is pretty much not possible (nor is it really recommended).
We will simply return a copy of the value in $to_clone.
As I said, this function (clone) is the central function in this inner package. All other functions are called by this function, and unless you have really specific needs will likely never been used by others.
This function will assume that $to_clone is an object, and try to follow the guidelines above where they pertain to objects. However, if $to_clone is not an object, and instead an unblessed reference, this function will pass $to_clone to cloneRef for cloning.
cloneRef
If $to_clone is not a reference of some kind and $cache is not a HASH reference an exception will be thrown.
This function will deep copy the reference value in $to_clone, which will result in recursive calls to the Class::Cloneable::Util::clone function for all the values found inside $to_clone.
This module places no restrictions upon it's subclasses, the user is free to compose their subclasses with just about any type of referent they like; HASH, SCALAR, ARRAY being the most common. However some of the more exotic and rare object construction styles will likely not work as expected (if at all).
For instance, CODE references and closures are incredibly difficult (if not impossible) to clone correctly, objects created from them are not recommended as they are unlikely to work since we cannot accurately clone them. GLOB and RegExp references are also not cloned, and so will not work correctly. However, there is nothing preventing you from just using Class::Cloneable for the sake of interface polymorphism, and implementing your own clone method with these types of objects.
It is also doubtful that this will work with things like the "Inside-Out" object technique since with this technique object data is not actually stored in the instance, but in a lexical package variable which is keyed by the stringified instance. We can only copy what is found within the actual object instance, and not loosely linked data.
None that I am aware of. Of course, if you find a bug, let me know, and I will be sure to fix it.
This module makes an attempt to handle tied references, however, the way it approaches them is not ideal and potentially wrong in some cases. So use this with care in such situations.
I use Devel::Cover to test the code coverage of my tests, below is the Devel::Cover report on this module test suite.
------------------------ ------ ------ ------ ------ ------ ------ ------ File stmt branch cond sub pod time total ------------------------ ------ ------ ------ ------ ------ ------ ------ Class/Cloneable.pm 100.0 100.0 100.0 100.0 100.0 100.0 100.0 ------------------------ ------ ------ ------ ------ ------ ------ ------ Total 100.0 100.0 100.0 100.0 100.0 100.0 100.0 ------------------------ ------ ------ ------ ------ ------ ------ ------
If you need a general purpose cloning module, this is not the module for you, I recommend either Clone (because it's XS and fast) or Clone::PP (if you don't have access to a C compiler). This module only is meant to be used as a base class for objects which need to have cloning abilities, and can not be used outside of that environment.
I want to say first, that this module's code was based heavily on the code found in Clone::PP by Matthew Simon Cavalletto (which in turn was initially derived from Ref.pm by David Muir Sharnoff). Using the code in Clone::PP as a basis for the code in this module saved me a lot of time and I owe a debt to that module and it's author for releasing it Open Source so that this was possible.
Now, you may be wondering why I chose to make yet another cloning module?
My first reason has to do with how these other modules handle objects. Neither Clone and Clone::PP correctly respect object encapsulation. My personal feelings is that if an object does not want to be cloned, it should not be allowed to be cloned (for instance, you would never want to copy a Singleton object, as the whole idea behind a Singleton is that there is only one of them). Upon encountering an object, both Clone and Clone::PP will deep copy it, and therefore violate its encapsulation.
To be fair, if we are talking about really strict encapsulation, then Class::Cloneable violates this too, since it can be used to copy a subclass of Class::Cloneable in a way which technically violates its internal encapsulation. However, this is only for the "root" object, and any subsequent Class::Cloneable objects will be cloned using the clone method (and therefore respecting encapsulation). So while it is not perfect, I feel it is a good compromise between requiring all classes to compose their own clone method and allowing arbitrary deep cloning.
The second reason was to provide more flexibility for overriding a clone method in a subclass. The protected inner package of Class::Cloneable::Util can be used to provide a more fine grained approach to the cloning of your object's internals.
stevan little, <stevan@iinteractive.com>
Copyright 2004-2006 by Infinity Interactive, Inc.
http://www.iinteractive.com
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Class::Cloneable, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Class::Cloneable
CPAN shell
perl -MCPAN -e shell install Class::Cloneable
For more information on module installation, please visit the detailed CPAN module installation guide.