Jed Lund > Data-Walk-Extracted > Data::Walk::Prune

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::Prune - A way to say what should be removed

SYNOPSIS ^

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

        my $edward_scissorhands = with_traits(
                        'Data::Walk::Extracted',
                        ( 
                                'Data::Walk::Prune', 
                                'Data::Walk::Print',
                        ),
                )->new( change_array_size => 1, );#Default
        my  $firstref = {
                        Helping => [
                                'Somelevel',
                                {
                                        MyKey => {
                                                MiddleKey => {
                                                        LowerKey1 => 'low_value1',
                                                        LowerKey2 => {
                                                                BottomKey1 => 'bvalue1',
                                                                BottomKey2 => 'bvalue2',
                                                        },
                                                },
                                        },
                                },
                        ],
                };
        my      $result = $edward_scissorhands->prune_data(
                        tree_ref    => $firstref, 
                        slice_ref   => {
                                Helping => [
                                        undef,
                                        {
                                                MyKey => {
                                                        MiddleKey => {
                                                                LowerKey1 => {},
                                                        },
                                                },
                                        },
                                ],
                        },
                );
        $edward_scissorhands->print_data( $result );
    
        ######################################################################################
        #     Output of SYNOPSIS
        # 01 {
        # 02    Helping => [
        # 03            'Somelevel',
        # 04            {
        # 05                    MyKey => {
        # 06                            MiddleKey => {
        # 07                                    LowerKey2 => {
        # 08                                            BottomKey1 => 'bvalue1',
        # 09                                            BottomKey2 => 'bvalue2',
        # 10                                    },
        # 12                            },
        # 13                    },
        # 14            },
        # 15    ],
        # 16 },
        ######################################################################################

DESCRIPTION ^

This Moose::Role implements the method prune_data. It takes a $tree_ref and a $slice_ref and uses Data::Walk::Extracted. To remove portions of the 'tree_ref' defined by an empty hash ref (no keys) or an empty array ref (no positions) at all required points of the 'slice_ref'. The 'slice_ref' must match the tree ref up to each slice point. If the slice points are on a branch of the slice_ref that does not exist on the tree_ref then no cut takes place.

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 prune_data 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 .

prune_memory

Definition: When running a prune operation any branch called on the pruner that does not exist in the tree will not be used. This attribute turns on tracking of the actual cuts made and stores them for review after the method is complete. This is a way to know if the cut was actually implemented.

Default undefined

Range 1 = remember the cuts | 0 = don't remember

(see also)

Data::Walk::Extracted - Attributes

Methods ^

prune_data( %args )

Definition: This is a method used to remove targeted parts of a data reference.

Accepts: a hash ref with the keys 'slice_ref' and 'tree_ref' (both required). The slice ref can contain more than one 'slice' location in the data reference.

tree_ref This is the primary data ref that will be manipulated and returned changed.

slice_ref This is a data ref that will be used to prune the 'tree_ref'. In general the slice_ref should match the tree_ref for positions that should remain unchanged. Where the tree_ref should be trimmed insert either an empty array ref or an empty hash ref. If this position represents a value in a hash key => value pair then the hash key is deleted. If this position represents a value in an array then the position is deleted/cleared depending on the attribute change_array_size in Data::Walk::Extracted. If the slice ref diverges from the tree ref then no action is taken past the divergence, even if there is a mandated slice. (no auto vivication occurs!)

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

Example

        $pruned_tree_ref = $self->prune_data(
                tree_ref => $tree_data,
                slice_ref => $slice_data,
                prune_memory => 0,
        );

Returns: The $tree_ref with any changes

set_prune_memory( $Bool )

Definition: This will change the setting of the prune_memory attribute.

Accepts: 1 = remember | 0 = no memory

Returns: nothing

get_prune_memory

Definition: This will return the current setting of the prune_memory attribute.

Accepts: nothing

Returns: A $Bool value for the current state

has_prune_memory

Definition: This will indicate if the prune_memory attribute is set

Accepts: nothing

Returns: A $Bool value 1 = defined, 0 = not defined

clear_prune_memory

Definition: This will clear the prune_memory attribute value (Not the actual prune memory)

Accepts: nothing

Returns: A $Bool value 1 = defined, 0 = not defined

has_pruned_positions

Definition: This answers if any pruned positions were stored

Accepts: nothing

Returns: A $Bool value 1 = pruned cuts are stored, 0 = no stored cuts

get_pruned_positions

Definition: This returns an array ref of stored cuts

Accepts: nothing

Returns: an ArrayRef - although the cuts were defined in one data ref this will return one data ref per cut. Each ref will go to the root of the original data ref.

number_of_cuts

Definition: This returns the number of cuts actually made

Accepts: nothing

Returns: an integer

Caveat utilitor ^

deep cloning

Because this uses Data::Walk::Extracted the final $tree_ref is deep cloned where the $slice_ref passed through.

Supported Node types

ARRAY
HASH
SCALAR
UNDEF

Supported one shot attributes

explanation

prune_memory

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 pruning through Objects / Instances nodes

3. Support pruning through CodeRef nodes

4. Support pruning 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
_build_branch

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

Data::ModeMerge

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

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

Data::Walk::Clone - available Data::Walk::Extracted Role

syntax highlighting: