/ 
Data-Walk-Extracted-v0.013_001
River stage one • 1 direct dependent • 2 total dependents
/ Data::Walk::Graft

NAME

Data::Walk::Graft - A way to say what should be added

SYNOPSIS

    #!perl
	use Modern::Perl;
	use Moose::Util qw( with_traits );
	use Data::Walk::Extracted v0.011;
	use Data::Walk::Graft v0.007;
	use Data::Walk::Print v0.007;

	my  $gardener = with_traits( 
			'Data::Walk::Extracted', 
			( 
				'Data::Walk::Graft', 
				'Data::Walk::Clone',
				'Data::Walk::Print',
			) 
		)->new(
			sort_HASH => 1,# For demonstration consistency
		);
	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 );
    
    #####################################################################################
    #     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 		,
    # 14 		'ValueFive',
    # 15 	],
    # 16 },
    #####################################################################################

DESCRIPTION

This Moose::Role contains methods for adding a new branch ( or three ) to an existing data ref. The primary method is "graft_data" which uses Data::Walk::Extracted. Grafting is accomplished by sending a scion_ref that has additions that need to be made to a tree_ref.

Caveat utilitor

Supported Node types

ARRAY
HASH
SCALAR

Supported one shot Attributes

graft_memory

Deep Cloning the graft

In general grafted data is safer if the grafted portion is deep cloned prior to grafting. To facilitate this the graft_data method will call deep_clone at the point of graft if the method is available to the instance. One easy way to do this is by adding the Data::Walk::Clone Role when building the instance. This will provide all of the full deep cloning and partial cloning availabe in that Role with no additional work. If this module finds that deep_clone is not available then the data reference memory location pointer for the graft point of the 'scion_ref' will be passed directly. The other possibility is to deep_clone the entire scion_ref prior to sending it to the 'graft_data' method so that later if you change that same reference somewhere else in the program it won't populate through to the scion graft on the data tree. Adding a 'deep_clone' method on your own is another possiblity. The call used is;

$scion_ref = $self->deep_clone( $scion_ref );

USE

One way to join this role with Data::Walk::Extracted is the method 'with_traits' from Moose::Util. Otherwise see Moose::Manual::Roles.

Methods

graft_data( %args )

Definition: This will take a 'scion_ref' and use it to graft to a 'tree_ref'. Where the 'scion_ref' matches the 'tree_ref' no changes are made. When the 'scion_ref' has something different than that portion of the 'tree_ref' then that portion of the 'scion_ref' replaces that portion of the 'tree_ref'. The word 'IGNORE' can be used for positions in array nodes that are effectivly don't care states for the 'scion_ref'. For example if you wish to change the third element of an array node then placing 'IGNORE' in the first two positions will cause "graft_data" to skip the analysis of those positions (This saves replacating deep references in an array position). If a 'scion_ref' adds a position past the end of an array then all the remaining positions in the 'tree_ref' will be undefined.
Accepts: a hash ref with the keys 'scion_ref' and 'tree_ref'. The data_refs can contain any supported node types. If no 'tree_ref' is passed then the 'scion_ref' is returned in it's entirety. If an array position set to 'IGNORE' in the 'scion_ref' is never evaluated (for example a replacment is done higher in the data tree) then the grafted tree will contain 'IGNORE' in that element of the array not undef. See "TODO" for future support.
Returns: The $tree_ref with any changes (possibly deep cloned)

has_graft_memory

Definition: This will indicate if the attribute "graft_memory" is set
Accepts: nothing
Returns: 1 or 0

set_graft_memory

Definition: This will set the "graft_memory" attribute.
Accepts: 1 or 0
Returns: nothing

get_graft_memory

Definition: This will return the current value for the "graft_memory" attribute.
Accepts: nothing
Returns: 1 or 0

clear_graft_memory

Definition: This will un-set the "graft_memory" attribute.
Accepts: nothing
Returns: nothing

number_of_scions

Definition: This will return the number of scion points grafted in the most recent graft action if the "graft_memory" attribute is on.
Accepts: nothing
Returns: a positive integer

has_grafted_positions

Definition: This will indicate if any grafted positions were saved.
Accepts: nothing
Returns: 1 or 0

get_grafted_positions

Definition: This will return any saved grafted positions.
Accepts: nothing
Returns: an ARRAY ref of grafted positions. This will include one full data branch to the root for each position actually grafted.

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 appenders as the top keys. Additionally some attributes that meet the criteria can be passed to graft_data and will be adjusted for just that run of the method.

graft_memory

Definition: When running a 'graft_data' operation any branch of the scion_ref that does not terminate past the end of the tree ref or differ from the tree_ref will not be used. This attribute turns on tracking of the actual grafts made and stores them for review after the method is complete. This is a way to know if a graft was actually implemented.
Default undefined
Range 1 = remember the cuts | 0 = don't remember

See Also

Attributes in Data::Walk::Extracted affect the output.

GLOBAL VARIABLES

$ENV{Smart_Comments}

The module uses Smart::Comments with the '-ENV' option so setting the variable $ENV{Smart_Comments} will turn on smart comment reporting. There are three levels of 'Smartness' called in this module '### #### #####'. See the Smart::Comments documentation for more information.

SUPPORT

github Data-Walk-Extracted/issues

TODO

Support grafting through CodeRef nodes
Support grafting through Objects / Instances nodes

AUTHOR

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.

Dependancies

Data::Walk::Extracted
version
Moose::Role
MooseX::Types::Moose
Smart::Comments - With the -ENV variable set

SEE ALSO

Data::Walk::Clone - manufacturers reccommendation
Data::Walk
Data::Walker
Data::ModeMerge

1 POD Error

The following errors were encountered while parsing the POD:

Around line 395:

L<> starts or ends with whitespace