NAME

Clone::Closure - A clone that knows how to clone closures

SYNOPSIS

    use Clone::Closure qw/clone/;

    my $total;

    sub count {
        my $count;
        return sub { $count++, $total++ };
    }

    my $foo = count;
    my $bar = clone $foo;

    # $bar has its own copy of $count, but shares $total 
    # with $foo.

DESCRIPTION

This module provides a clone method which makes recursive copies of nested hash, array, scalar and reference types, including tied variables, objects, and closures.

clone takes a scalar argument. To duplicate arrays or hashes, pass them in by reference, e.g.

    my $copy = clone \@array;

    # or

    my %copy = %{ clone \%hash };

Values which are not cloned

Sub (except for "Closures"), glob, format and IO refs are simply duplicated, not cloned.

Closures

Closures are cloned, unlike with Clone. Closed-over lexicals will be cloned if they were originally declared in a scope that could be run more than once, and shared otherwise.

That is, in the example in the "SYNOPSIS", $count is cloned as it is scoped to &count, which can run many times with different $count variables; but $total is shared as it is file-scoped, so there will only ever be one copy.

Generally speaking, clone will produce what might have been another copy of the closure, generated by the same means. However, see "BUGS" below.

Magic

The following types of magic are preserved:

• shared variables

  Cloning a shared variable creates a new shared variable, but it is not shared with any other threads yet. That is, the clone is only visible in this thread and any threads you create later.

• tied variables

  The tied object will also be cloned.

• qr// compiled regexes

• tainted values

  Cloning a tainted value produces a tainted copy.

• globs

  Globs are not cloned. Cloning a glob returns the original glob.

• weakrefs

  Beware cloning weakrefs: cloning a reference also clones the object it refers to, and if there are no strong refs to this new object it will self-destruct before clone returns. For example,

      my $sv  = 5;
      my $ref = \$sv;
      weaken $ref;
      my $clone = clone $ref;

  will result in $clone being undef, as the new clone of $sv has no (strong) referents. As weakrefs are normally used to break loops in self-referential structures, this should not happen often.

• custom magic (U, u, and ~ magics)

  These will be cloned, and if the magic has a mg_obj that will be cloned too. This is not necessarily the right thing to do, depending on what the custom magic is being used for.

• Boyer-Moore fast string search

• vstring magic

• UTF8 cache magic

  These types of magic are not visible from Perl-space, and are used by perl to optimize certain operations.

All other types of magic are dropped when cloning, so for example

    my $env = clone \%ENV;

will produce a normal hashref containing a copy of the environment.

BUGS

Loops

Loops are currently not correctly recognized as 'scopes that may run more than once'. That is, given

    my @subs;

    for my $i (1..10) {
        push @subs, sub { $i };
    }

a clone of $subs[0] will share $i, which is probably not what you wanted. One possible workaround is to generate the closure in a sub, with its own lexical; for example

    my @subs;

    sub make_closure {
        # this is important, so we get a new lexical
        my $i = shift;
        
        return sub { $i };
    }

    for my $i (1..10) {
        push @subs, make_closure $i;
    }

A clone of $subs[0] will now have its own copy of $i.

Note that this behaviour will change in a future release; unfortunately, I can't provide a warning (as I haven't worked out how to detect loops...).

5.6 and eval STRING

Under 5.6, lexicals which are closed over by eval STRING will always be cloned, never shared. That is, given

    my $x;
    my $sub = eval 'sub { $x }';

a clone of $sub will have its own copy of $x, which is incorrect.

TODO

• Fix the loop bug.

• Do something sensible with fieldhashes.

• Provide a means to specify what is cloned and what copied.

AUTHOR

This module is based on Clone v0.23 by Ray Finch, <rdf@cpan.org>.

Clone is copyright 2001 Ray Finch.

This module is copyright 2007 Ben Morrow, <ben@morrow.me.uk>.

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

SEE ALSO

Clone, Storable.

cpanm Clone::Closure

perl -MCPAN -e shell
install Clone::Closure