Data::Walk::Graft - A way to say what should be added
#!perl
use Modern::Perl;
use Moose::Util qw( with_traits );
use lib '../lib', 'lib';
use Data::Walk::Extracted 0.019;
use Data::Walk::Graft 0.013;
use Data::Walk::Print 0.015;
my $gardener = with_traits(
'Data::Walk::Extracted',
(
'Data::Walk::Graft',
'Data::Walk::Clone',
'Data::Walk::Print',
)
)->new(
sorted_nodes =>{
HASH => 1,
},# For demonstration consistency
#Until Data::Walk::Extracted and ::Graft support these types
#(watch Data-Walk-Extracted on github)
skipped_nodes =>{
OBJECT => 1,
CODEREF => 1,
},
graft_memory => 1,
);
my $tree_ref = {
Helping =>{
KeyTwo => 'A New Value',
KeyThree => 'Another Value',
OtherKey => 'Something',
},
MyArray =>[
'ValueOne',
'ValueTwo',
'ValueThree',
],
};
$gardener->graft_data(
scion_ref =>{
Helping =>{
OtherKey => 'Otherthing',
},
MyArray =>[
'IGNORE',
{
What => 'Chicken_Butt!',
},
'IGNORE',
'IGNORE',
'ValueFive',
],
},
tree_ref => $tree_ref,
);
$gardener->print_data( $tree_ref );
print "Now a list of -" . $gardener->number_of_scions . "- grafted positions\n";
$gardener->print_data( $gardener->get_grafted_positions );
#####################################################################################
# Output of SYNOPSIS
# 01 {
# 02 Helping => {
# 03 KeyThree => 'Another Value',
# 04 KeyTwo => 'A New Value',
# 05 OtherKey => 'Otherthing',
# 06 },
# 07 MyArray => [
# 08 'ValueOne',
# 09 {
# 10 What => 'Chicken_Butt!',
# 11 },
# 12 'ValueThree',
# 13 undef,
# 14 'ValueFive',
# 15 ],
# 16 },
# 17 Now a list of -3- grafted positions
# 18 [
# 19 {
# 20 Helping => {
# 21 OtherKey => 'Otherthing',
# 22 },
# 23 },
# 24 {
# 25 MyArray => [
# 26 undef,
# 27 {
# 28 What => 'Chicken_Butt!',
# 29 },
# 30 ],
# 31 },
# 32 {
# 33 MyArray => [
# 34 undef,
# 35 undef,
# 36 undef,
# 37 undef,
# 38 'ValueFive',
# 39 ],
# 40 },
# 41 ],
#####################################################################################
This Moose::Role contains methods for adding a new branch ( or three ) to an existing data ref. The method used to do this is graft_data using Data::Walk::Extracted. Grafting is accomplished by sending a scion_ref that has additions that need to be made to a tree_ref. Anything in the scion ref that does not exist in the tree ref is grafted to the tree ref.
This is a Moose::Role. One way to incorporate this role into Data::Walk::Extracted. is MooseX::ShortCut::BuildInstance. or read Moose::Util for more class building information.
In general grafted data refs are subject to external modification by changing the data in that ref from another location of the code. This module assumes that you don't want to do that! As a consequence it checks to see if a 'deep_clone' method has been provided to the class that consumes this role. If so it calls that method on the data ref to be grafted. One possiblity is to add the Role Data::Walk::Clone to your object so that a deep_clone method is automatically available (all compatability testing complete). If you choose to add your own deep_clone method it will be called like this;
my $clone_value = ( $self->can( 'deep_clone' ) ) ?
$self->deep_clone( $scion_ref ) : $scion_ref ;
Where $self is the active object instance.
If you want to add data from another ref to a current ref and the add ref contains nodes that are not supported then you need to skip those nodes in the cloning process.
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 graft_data and will pass through to any deep_clone call as well. These attributes are called 'one shot' attributes.
Attributes in Data::Walk::Extracted affect the output.
$grafted_tree_ref = $self->graft_data(
tree_ref => $tree_data,
scion_ref => $addition_data,
graft_memory => 0,
);
Support for Objects is partially implemented and as a consequence _process_the_data won't immediatly die when asked to parse an object. It will still die but on a dispatch table call that indicates where there is missing object support not at the top of the node.
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 '#####'.
Implemented with an attribute that turns the feature on and off. The goal would be to eliminate unintentional swapping of small branches for large branches. This feature has some overhead downside and may not be usefull so I'm not sure if it makes sence yet.
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.
