Jed Lund > Data-Walk-Extracted-0.024.004 > Data::Walk::Clone

Download:
Data-Walk-Extracted-0.024.004.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: v0.24.4   Source  

NAME ^

Data::Walk::Clone - deep data cloning with boundaries

SYNOPSIS ^

        #!perl
        use Moose::Util qw( with_traits );
        use Data::Walk::Extracted;
        use Data::Walk::Clone;

        my $dr_nisar_ahmad_wani = with_traits( 
                        'Data::Walk::Extracted', 
                        ( 'Data::Walk::Clone',  ) 
                )->new( 
                        skip_node_tests =>[  [ 'HASH', 'LowerKey2', 'ALL',   'ALL' ] ],
                );
        my  $donor_ref = {
                Someotherkey    => 'value',
                Parsing         =>{
                        HashRef =>{
                                LOGGER =>{
                                        run => 'INFO',
                                },
                        },
                },
                Helping =>[
                        'Somelevel',
                        {
                                MyKey =>{
                                        MiddleKey =>{
                                                LowerKey1 => 'lvalue1',
                                                LowerKey2 => {
                                                        BottomKey1 => 'bvalue1',
                                                        BottomKey2 => 'bvalue2',
                                                },
                                        },
                                },
                        },
                ],
        };
        my      $injaz_ref = $dr_nisar_ahmad_wani->deep_clone(
                        donor_ref => $donor_ref,
                );
        if(
                $injaz_ref->{Helping}->[1]->{MyKey}->{MiddleKey}->{LowerKey2} eq
                $donor_ref->{Helping}->[1]->{MyKey}->{MiddleKey}->{LowerKey2}           ){
                print "The data is not cloned at the skip point\n";
        }
                
        if( 
                $injaz_ref->{Helping}->[1]->{MyKey}->{MiddleKey} ne
                $donor_ref->{Helping}->[1]->{MyKey}->{MiddleKey}                ){
                print "The data is cloned above the skip point\n";
        }

        #####################################################################################
        #     Output of SYNOPSIS
        # 01 The data is not cloned at the skip point
        # 02 The data is cloned above the skip point
        #####################################################################################

DESCRIPTION ^

This Moose::Role contains methods for implementing the method deep_clone using Data::Walk::Extracted. This method is used to deep clone (clone many/all) levels of a data ref. Deep cloning is accomplished by sending a 'donor_ref' that has data nodes that you want copied into a different memory location. In general Data::Walk::Extracted already deep clones any output as part of its data walking so the primary value of this role is to manage deep cloning boundaries. It may be that some portion of the data should maintain common memory references to the original memory references and so all of the Data::Walk::Extracted skip methods will be recognized and supported. Meaning that if a node is skipped the data reference will be copied directly rather than cloned. The deep clone boundaries are managed using the skip attributes in Data::Walk::Extracted.

USE

This is a Moose::Role specifically designed to be used with Data::Walk::Extracted . It can be combined traditionaly to the ~::Extracted class using Moose methods or for information on how to join this role to Data::Walk::Extracted at run time see Moose::Util or MooseX::ShortCut::BuildInstance for more information.

Attributes ^

Data passed to ->new when creating an instance. For modification of these attributes see Methods. The ->new function will either accept fat comma lists or a complete hash ref that has the possible attributes as the top keys. Additionally some attributes that have all the following methods; get_$attribute, set_$attribute, has_$attribute, and clear_$attribute, can be passed to deep_clone and will be adjusted for just the run of that method call. These are called 'one shot' attributes. The class and each role (where applicable) in this package have a list of 'supported one shot attributes'.

should_clone

Definition: There are times when the cloning needs to be turned off. This is the switch. If this is set to 0 then deep_clone just passes the doner ref back.

Default undefined = everything is cloned

Range Boolean values (0|1)

(see also)

Data::Walk::Extracted Attributes

Methods ^

deep_clone( $arg_ref|%args|$data_ref )

Definition: This takes a 'donor_ref' and deep clones it.

Accepts: either a single data reference or named arguments in a fat comma list or hashref

Hash option - if data comes in a fat comma list or as a hash ref and the keys include a 'donor_ref' key then the list is processed as such.

donor_ref - this is the data reference that should be deep cloned - required

[attribute name] - attribute names are accepted with temporary attribute settings. These settings are temporarily set for a single "deep_clone" call and then the original attribute values are restored. For this to work the the attribute must meet the necessary criteria.

single data reference option - if only one data_ref is sent and it fails the test;

        exists $data_ref->{donor_ref}

then the program will attempt to name it as donor_ref => $data_ref and then clone the whole thing.

Returns: The deep cloned data reference

get_should_clone

Definition: This will get the current value of the attribute should_clone

Accepts: nothing

Returns: a boolean value

set_should_clone( $Bool )

Definition: This will set the attribute should_clone

Accepts: a boolean value

Returns: nothing

has_should_clone

Definition: This will return true if the attribute should_clone is active

Accepts: nothing

Returns: a boolean value

clear_should_clone

Definition: This will set the attribute should_clone to one ( 1 ). The name is awkward to accomodate one shot attribute changes.

Accepts: nothing

Returns: nothing

Caveat utilitor ^

Supported Node types

ARRAY
HASH
SCALAR

GLOBAL VARIABLES ^

$ENV{Smart_Comments}

The module uses Smart::Comments if the '-ENV' option is set. The 'use' is encapsulated in an if block triggered by an environmental variable to comfort non-believers. Setting the variable $ENV{Smart_Comments} in a BEGIN block will load and turn on smart comment reporting. There are three levels of 'Smartness' available in this module '###', '####', and '#####'.

SUPPORT ^

github Data-Walk-Extracted/issues

TODO ^

1. Add Log::Shiras debugging in exchange for Smart::Comments

2. Support cloning through class instance nodes (can should you even do this?)

3. Support cloning through CodeRef nodes

4. Support cloning through REF nodes

AUTHOR ^

Jed Lund
jandrew@cpan.org

COPYRIGHT ^

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

The full text of the license can be found in the LICENSE file included with this module.

This software is copyrighted (c) 2013 by Jed Lund.

Dependencies ^

version

Moose::Role

requires

_process_the_data
_dispatch_method
_get_had_secondary

MooseX::Types::Moose

Data::Walk::Extracted

Data::Walk::Extracted::Dispatch

SEE ALSO ^

Smart::Comments - is used if the -ENV option is set

Data::Walk

Data::Walker

Storable - dclone

Data::Walk::Print - available Data::Walk::Extracted Role

Data::Walk::Graft - available Data::Walk::Extracted Role

Data::Walk::Prune - available Data::Walk::Extracted Role

syntax highlighting: