NAME
Data::Walk::Clone - deep data cloning with boundaries
SYNOPSIS
#!perl
use Modern::Perl;
use Moose::Util qw( with_traits );
use Data::Walk::Extracted v0.015;
use Data::Walk::Clone v0.005;
my $dr_nisar_ahmad_wani = with_traits(
'Data::Walk::Extracted',
( 'Data::Walk::Clone', )
)->new(
skip_clone_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 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 define deep cloning boundaries. It may be that some portion of the data should maintain common memory location pointers to the original memory locations and so two ways of defining where to stop deep cloning are provided. First a level callout where deep cloning can stop at a common level. Second a matching tool where key or node type matching can be done across multiple levels or only at targeted levels.
Caveat utilitor
Supported Node types
- ARRAY
- HASH
- SCALAR
Supported one shot "Attributes"
- clone_level
- skip_clone_tests
- should_clone
USE
This is a Moose::Role and can be used as such. One way to use this role with Data::Walk::Extracted, is the method 'with_traits' from Moose::Util. Otherwise see Moose::Manual::Roles.
Methods
deep_clone( $arg_ref|%args )
- 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
-
- named variable 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 variable option - if only one data_ref is sent and it fails the test for "exists $data_ref->{donor_ref}" then the program will attempt to name it as donor_ref => $data_ref and then process the data as a fat comma list.
- Returns: The deep cloned data reference
has_clone_level
- Definition: This will indicate if the attribute clone_level is set
- Accepts: nothing
- Returns: 1 or 0
get_clone_level
- Definition: This will return the currently set clone_level attribute value
- Accepts: nothing
- Returns: the level as an integer number or undef for nothing
set_clone_level( $int )
- Definition: This will set the clone_level attribute
- Accepts: a positive integer
- Returns: nothing
clear_clone_level
- Definition: This will clear the clone_level attribute
- Accepts: nothing
- Returns: nothing
get_skip_clone_tests
- Definition: This will return an ArrayRef[ArrayRef] with all skip tests for the skip_clone_tests attribute
- Accepts: nothing
- Returns: an ArrayRef[ArrayRef]
set_skip_clone_tests( [ [ $type, $key, $position, $level ], ] )
- Definition: This will take an ArrayRef[ArrayRef] with all skip tests for the skip_clone_tests attribute and replace any existing tests with the new list.
- Accepts: ArrayRef[ArrayRef]
- Returns: nothing
add_skip_clone_test( [ $type, $key, $position, $level ] )
- Definition: This will add one array ref skip test callout to the skip_clone_tests attribute list
- Accepts: [ $type, $key, $position, $level ]
- Returns: nothing
has_skip_clone_tests
- Definition: This will return the number of skip tests called out in the skip_clone_tests attribute list
- Accepts: nothing
- Returns: a positive integer indicating how many array positions there are
clear_skip_clone_tests
- Definition: This will clear the the skip_clone_tests attribute list
- Accepts: nothing
- Returns: nothing
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 on ( 1 ). The name is awkward to accomodate one shot attribute changes.
- Accepts: nothing
- Returns: nothing
Attributes
Data passed to ->new when creating an instance using a class. 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 appenders 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.
clone_level
- Definition: When running a clone operation it is possible to stop cloning and use the actual data references in the original data structure below a certain level. This sets the boundary for that level.
- Default undefined = everything is cloned
- Range positive integers (3 means clone to the 3rd level)
skip_clone_tests
- Definition: When running a clone operation it is possible to stop cloning and use the actual data references in the original data structure at clearly defined trigger points. This is the way to define those points. The definition can test against array position, match a hash key, also only test at a level (Testing at level 0 is not supported!), and can use eq or =~ when matching. The attribute is passed an ArrayRef of ArrayRefs. Each sub_ref contains the following.
-
- $type - this is any of the allowed reference node types
- $key - this is either a scalar or regexref to use for matching a hash key
- $position - this is used to match an array position can be an integer or 'ANY'
- $level - this restricts the skipping test usage to a specific level only or 'ANY'
- Example
-
[ [ 'HASH', 'KeyWord', 'ANY', 'ANY'], # Dont clone the value of any hash key eq 'Keyword' [ 'ARRAY', 'ANY', '3', '4'], ], #Don't clone the data in arrays at position three on level four ] - Range an infinite number of skip tests added to an array
- Default [] = no cloning is skipped
should_clone
- Definition: There are times when the cloning is built into code by adding the role to a class but you want to turn it off. This attribute will cause the deep_clone function to return the donor_ref pointer as the cloned_ref.
- Default 1 = cloning occurs
- Range 1 | 0 = no cloning
Attributes in Data::Walk::Extracted can affect the output.
GLOBAL VARIABLES
- $ENV{Smart_Comments}
-
The module uses Smart::Comments if the '-ENV' option is set. The 'use' is encapsulated in a BEGIN block triggered by the environmental variable to comfort non-believers. Setting the variable $ENV{Smart_Comments} will load and turn on smart comment reporting. There are three levels of 'Smartness' available in this module '### #### #####'.
SUPPORT
TODO
AUTHOR
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.
Dependencies
SEE ALSO
- Smart::Comments - is used if the -ENV option is set
- Data::Walk
- Data::Walker
- Storable - dclone
- Data::Walk::Print
- Data::Walk::Prune
- Data::Walk::Graft
1 POD Error
The following errors were encountered while parsing the POD:
- Around line 672:
L<> starts or ends with whitespace