NAME

SYNOPSIS

        use Clone::More qw( clone );

        my $structure = [
                { 'key' => 'value' }
        ];

        for my $set ( @$structure ) {
                my $clone = clone( $set );
                
                for ( keys %$clone ) {
                        print "Everything matches" if ( exists( $set->{$_} ) && $set->{$_} eq $clone->{$_} );
                }
        }

DESCRIPTION

Please take a look at the WARNINGS, GOTCHAS and FUTURE DEVELOPMENT sections, as resources to see if this module is fully capable of doing everything that you want it to do (and it will do most everything).

        use Clone::More qw( clone );

        my $foo = { 'a' => 'b' };
        my $bar = { 'a' => $foo, 'b' => $foo };

        my $baz = clone( $bar );

        print "\$foo and \$bar are different references\n" if ( $foo ne $bar );
        print "\$foo->{'a'} and \$bar->{'a'} are different references\n" if ( $foo->{'a'} ne $bar->{'a'} );
        print "\$foo->{'a'} and \$foo->{'b'} are the same, however\n" if ( $foo->{'a'} eq $bar->{'b'} );

        use Clone::More qw( circular );

        my @a;
        $a[0] = \@a;

        my @b;
        $b[0] = { 'key' => 'value' };

        # Will print '@a has a circular reference'
        print ( ( circular( \@a ) ) ? "\@a has a circular reference\n" : "\@a has NO circular reference\n" );

        # Will print '@b has NO circular reference'
        print ( ( circular( \@b ) ) ? "\@b has a circular reference\n" : "\@b has NO circular reference\n" )

        my $circular = [ qw( one two ) ];
        $circular->[2] = \$r;
        $circular->[3] = \$r;
        $circular->[4] = \$r;

        my $not_circ = [ qw( one two ) ];
        my $wth_circ = [ qw( one two ) ];
        $r->[2] = \$wth_circ;
        $r->[3] = \$wth_circ;
        $r->[4] = \$wth_circ;

        use Clone::More qw( circular is_circular );

        my @a;
        $a[0] = \@a;

        my @b;
        $b[0] = { 'key' => 'value' };

        print "1" if ( circular( \@a ) == is_circular( \@a ) );
        print "1" if ( circular( \@b ) == is_circular( \@b ) );
        print "0" if ( circular( \@a ) == is_circular( \@b ) );
        print "\n";
        
        # You will see the following printed to STDOUT:
        # '110'

PROGRAMATIC HOOKS

        package Hookable;

        use strict;
        use warnings;

        use Clone::More qw( clone );
        
        sub new { bless {}, shift }

        sub CLONEMORE_clone {

                # Where clone is the cloned object from the source, where source
                # was the originating reference
                my ( $clone, $source ) = @_;

                # I am going to pretend the source has a list of defined methods,
                # of which I want to clone and transfer to the clone; outside
                # of the blessed hash-refrence that is the source of the object
                $clone->$_( clone( $source->$_() ) ) for ( qw( get_method_1 get_method_2 get_method_3 ) );

                # At this point, the cloned object will also have a set of cloned
                # fields from the source.  If, by chance, any of the values of the
                # defined attribtes are other 'Hookable' objects, the same routine
                # will be called on that object as well.
                
                # The API requires me to return the new $clone, this will be returned to
                # the caller
                return $clone;
        }

        #!/usr/bin/perl -w
        
        use strict;

        use Clone::More qw( clone );

        my $hookable  = Hookable->new();
        $hookable->{'hash_stuff'} = 'some value';
        
        my $structure = {
                'hookable' => $hookable,
                'new'      => Hookable->new(),
                'deeply'   => {
                        'hookable' => $hookable,
                        'new'      => Hookable->new();
                },
        };

        my $cloned = clone( $sturcture );

CONFIGURATION VARIABLES

$Clone::More::ALLOW_HOOKS

The "ALLOW_HOOKS" variable will allow for the toggling behavior, telling "Clone::More" to check for hooks when cloning objects. (See "PRGRAMATIC HOOKS" for more details). The varialble will default to 'on', where "Clone::More" will always check each object for hooks defined within the object.

        use Clone::More qw( clone );
        
        $Clone::More::ALLOW_HOOKS = 1; # No need, this is default

        my $object = HasHooks->new();

        package HasHooks;

        use strict;
        use warnings;

        sub new { bless {}, shift }

        sub CLONEMORE_clone {
                my ( $clone, $source ) = @_;

                # Re-assigning the reference will now return the reference from the
                # C<Clone::More::clone> when cloning a HasHooks object, rather than
                # a cloned reference to the object.
                $clone = { 'object' => $clone };
                return $clone;
        }
    

$Clone::More::BREAK_REFS

        use Clone::More qw( clone );
        $Clone::More::BREAK_REFS = 1;

        my $foo = { 'a' => 'b' };
        my $bar = { 'a' => $foo, 'b' => $foo };

        my $baz = clone( $bar );

        print "\$foo and \$bar are different references\n" if ( $foo ne $bar );
        print "\$foo->{'a'} and \$bar->{'a'} are different references\n" if ( $foo->{'a'} ne $bar->{'a'} );
        print "\$foo->{'a'} and \$foo->{'b'} are no longer the same\n" if ( $foo->{'a'} ne $bar->{'b'} );
    

You will see that by adding the BREAK_REFS flag, you will change the overall behavior of the routine. The BREAK_REFS flag must, simply, have truthfullness (as far as Perl is concerned) in order to be 'on'.

Whereas:

        $Clone::More::BREAK_REFS = 1;

        # Will do the same thing as:
        
        $Clone::More::BREAK_REFS = 'yes';

        # Will do the same thing as:
        
        $Clone::More::BREAK_REFS = ( 2 != 1 );
    

Albeit handy, this feature may also slow down the module by some degree. Therefore, there is some flexibility into whether or not you need to use this, and the functionality can be compiled out of the object; speeding up the cloning ability. Therefore, Re-compiling the mdule without MINDFUL_REFS will increase the speed of the module by a degree of 3x! If you KNOW you will never use the $Clone::More::BREAK_REFS and are confident with manually installing Perl modules from source, it is recommended you do so. There are comments in the XS source that will detail how to do this.

This configuration only applies to the "Clone::More::clone" routine.

$Clone::More::IGNORE_CIRCULAR

This configuration flag will tell Clone to ignore all circular reference checks. Unless you are completely confident the structures that are being cloned WILL NEVER contain a circular reference, it is not fully recommended to use this configuration variable.

By default, this variable is turned 'off'. To toggle, the variable must simply evaulate to true in Perl.

Whereas:

        $Clone::More::IGNORE_CIRCULAR = 1;

        # Will do the same thing as:
        
        $Clone::More::IGNORE_CIRCULAR = 'yes';

        # Will do the same thing as:
        
        $Clone::More::IGNORE_CIRCULAR = ( 2 != 1 );
    

This configuration only applies to the "Clone::More::clone" routine.

$Clone::More::CIRCULAR_ACTION

This configuration is mutually exclucive of the $Clone::More::IGNORE_CIRCULAR. More specifically, the variable will only be validiated when $Clone::More::IGNORE_CIRCULAR is turned 'off' (by default).

This configuration is currently a bit-mask operator, telling "Clone::More::clone" what to do when it comes across a circular reference. By default, the zero bit is assigned to the configuration, telling "Clone::More::clone" to create a new circular reference within the new structure (no longer referencing the source of the clone).

It should be noted that the current version of "Clone::More" will use the bit-mask as a literal integer, though wanted to incept the idea of having a bit-mask here to allow for future development. The useage of bit-wise OR ('|') will do nothing but warn and default to the zero-bit.

Operations include:

EXAMPLES

Using Clone::More::clone

"Clone::More::clone" is an exported routine. You can either use it as such, or simply call it directly on the package.

Example w/ export:

        use Clone::More qw( clone );

        my $source = { 'a' => 'b' };
        my $clone  = clone( $source );
    

Example w/o export

        use Clone::More;

        my $source = { 'a' => 'b' };
        my $clone  = Clone::More::clone( $source );
    

Using Clone::More::(is_)?circular

The "Clone::More::(is_)?circular" routines will allow you to test whether or not a structure contains a ciruclar reference or not.

GOTCHAS/WARNINGS

bless()'ed references (Perl objects)

This module works great for blessed references, how ever the paradigm changes when trying to clone inside out objects (or Conway's 'flywaight' style of object creation). Clone does not, nor will not, clone the stash of an object's class; this would break more than anything. Given this, HOOKS have been provided in order to programatically handle wierd stuff like this. I am hoping applications, developers and all of the like whom are using inside out objects will know what the heck it is I'm talking about here. There is a lot more information about this in the PROGRAMATIC HOOKS section.

ithreads

I really have no idea how this will work in a treadded environment. It should be OK, but there is no development that has taken this into account.

Hooks and circular evaluations

Both Clone hooks and deep circular evaluations are pretty new, and may have some problems within them. Please, if you find anything you don't expect; feel free to bug it and I will try to patch it up ASAP.

OPTIMIZATION HACKS

I'm not going to explain much more, though if you are relitively tuned up in your C, you can take a gander at the XS implementation and play around with it if you'd like!

SEE ALSO

Storable

This will, essentially, do the exact same thing as what this module does. The difference being that Storable will freeze the chunk of memory you are trying to clone, and thaw that binary chunk to another piece of memory. This works well, yet is very slow. Subsiquently, Storable, as of Perl 5.8, is CORE; and may be more trusted than this :)

Clone

The 'basis' of "Clone::More", where Clone is simply a very optimized version of "Clone::More". Where hooks, some exported routines and advanced functionality have been removed.

AUTHOR

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.