NAME

CXC::Data::Visitor - Invoke a callback on every element at every level of a data structure.

VERSION

version 0.05

SYNOPSIS

use CXC::Data::Visitor 'visit', 'RESULT_CONTINUE';

my $hoh = { fruit => { berry => 'purple' }, };

visit(
    $hoh,
    sub {
        my ( $key, $vref ) = @_;
        $$vref = 'blue' if $key eq 'berry';
        return RESULT_CONTINUE;
    } );

say $hoh->{fruit}{berry}    # 'blue'

DESCRIPTION

CXC::Data::Visitor provides a means of performing a depth first traversal of a data structure. There are similar modules on CPAN ("SEE ALSO"); this module provides a few extras:

The traversal may be aborted.
A container (hash or array) may be immediately revisited if the callback requests it.
An element whose value is a container may be revisited after the container is visited if the callback requests it.
User selectable behavior upon detection of a traversal cycle.
The complete path from the structure route to an element (both the ancestor containers and the keys and indexes required to traverse the path) is available.

SUBROUTINES

visit

( $completed, $context, $metadata ) = visit( $struct, $callback, %opts );

Perform a depth-first traversal of $struct, invoking $callback on containers (hashes and arrays) and terminal elements in $struct.

Blessed hashes or arrays are treated as terminal elements and are not further traversed.
Hashes are traversed in sorted key order.
Cycles are detected upon traversing a container a second time in a depth first search.
Containers that can be reached multiple times without cycling, e.g.
```
%hash = ( a => { b => 1 }, );
$hash{c} = $hash{a};
```
are visited once per parent, e.g.
```
{a}, {a}{b}, {a}{b}[0]
{c}, {c}{b}, {c}{b}[0]
```
$callback is first invoked on a container and then its elements. Given
```
{ a => { b => [ 0 ], c => 2 } }
```
the callback order is
```
{a}, {a}{b}, {a}{b}[0], {a}{c}
```

"visit" returns the following:

$completed => Boolean: true if all elements were visited, false if $callback requested a premature return.
$context => hash: a hash made available to $callback to stash data
$metadata => hash: collected metadata. See "$metadata" below.

$callback will be called as:

$handle_return = $callback->( $kydx, $vref, $context, \%metadata );

and should return one of the following (see "EXPORTS" to import the constants):

RESULT_CONTINUE

The process of visiting elements should continue.

RESULT_RETURN

"visit" should return immediately to the caller.

RESULT_REVISIT_CONTAINER

Further processing of the elements in the current container should stop and the container should be revisited. This allows "$callback" to modify the container and have it reprocessed.

To avoid inadvertent infinite loops, a finite number of revisits is allowed during a traversal of a container (see "revisit_limit"). Containers with multiple parents are traversed once per parent; The limit is reset for each traversal.

RESULT_REVISIT_ELEMENT

If the value of this element is a container, it should be revisited (by calling "$callback") after its value is visited. This allows post-processing results when travelling back up the structure.

During the initial visit

$metadataa->{pass} & PASS_VISIT_ELEMENT

will be true. During the followup visit

$metadata->{pass} & PASS_REVISIT_ELEMENT

will be true and "$callback" may only return values of RESULT_RETURN and RESULT_CONTINUE; any other values will cause an exception.

The ordered contents of the $metadata{path} array uniquely identify an element, so may be used to track elements using external data structures. Do not depend upon reference addresses remaining constant.

"$callback" is passed

$kydx

the key or index into $container of the element being visited.

$vref

a reference to the value of the element being visited. Use $$vref to get the actual value.

$context

A hash which can be used by the caller to stash data.

$metadata

A hash of state information kept by CXC::Data::Visitor, but which may be of interest to the callback:

container: a reference to the hash or array which contains the element being visited.
path: An array which contains the path (keys and indices) used to arrive at the current element from $struct.
ancestors: An array contains the ancestor containers of the current element.

pass

A constant indicating the current visit pass through an element.

%opts may contain the following entries:

context => hashref

A reference to a hash passed to "$callback", for the caller's use. It defaults to a freshly created hash.

cycle => CYCLE_TRUNCATE | CYCLE_DIE | CYCLE_CONTINUE | <$coderef>

How to handle cycles in the data structure.

See "EXPORTS" to import the constant values.

CYCLE_DIE

Throw an exception (the default).

CYCLE_CONTINUE

Pretend we haven't seen it before. Will cause stack exhaustion if $callback does handle this.

CYCLE_TRUNCATE

Truncate before entering the cycle a second time.

$coderef

Examine the situation and request a particular resolution. $coderef is called as

$coderef->( $container, $context, $metadata );

where $container is the hash or array which has already been traversed. See below for "$context" and "$metadata".

$coderef should return one of CYCLE_DIE, CYCLE_CONTINUE, or CYCLE_TRUNCATE, indicating what should be done.

visit => VISIT_HASH | VISIT_ARRAY | VISIT_CONTAINER | VISIT_LEAF | VISIT_ALL

The parts of the structure that will trigger a callback. See "EXPORTS" to import the constants.

VISIT_CONTAINER

Invoke "$callback" on containers (either hashes or arrays). For example, the elements in the following structure

$struct = { a => { b => 1, c => [ 2, 3 ] } }

passed to "$callback" are:

a => {...}  # $struct->{a}
c => [...]  # $struct->{c}

VISIT_ARRAY

VISIT_HASH

Only visit containers of the given type.

VISIT_LEAF

Invoke "$callback" on terminal (leaf) elements. For example, the elements in the following structure

$struct = { a => { b => 1, c => [ 2, 3 ] } }

passed to "$callback" are:

b => 1  # $struct->{a}{b}
0 => 2  # $struct->{a}{c}[0]
1 => 3  # $struct->{a}{c}[1]

VISIT_ALL

Invoke "$callback" on all elements. This is the default.

revisit_limit

If "$callback" returns RESULT_REVISIT_CONTAINER, then the parent container of the element is re-scanned for its elements and revisited. To avoid an inadvertent infinite loop, an exception is thrown if the parent container is revisited more than this number of times. It defaults to 10;

EXPORTS

This module uses Exporter::Tiny, which provides enhanced import utilities.

The following symbols may be exported:

visit
VISIT_CONTAINER VISIT_LEAF VISIT_ALL
CYCLE_DIE CYCLE_CONTINUE CYCLE_TRUNCATE
RESULT_RETURN RESULT_CONTINUE RESULT_REVISIT_CONTAINER RESULT_REVISIT_ELEMENT
PASS_VISIT_ELEMENT PASS_REVISIT_ELEMENT

The available tags and their respective imported symbols are:

all

Import all symbols.

results

RESULT_RETURN RESULT_CONTINUE
RESULT_REVISIT_CONTAINER RESULT_REVISIT_ELEMENT

cycles

CYCLE_DIE CYCLE_CONTINUE CYCLE_TRUNCATE

visits

VISIT_CONTAINER VISIT_LEAF VISIT_ALL

passes

PASS_VISIT_ELEMENT PASS_REVISIT_ELEMENT

constants

Import tags results, cycles, visits.

SUPPORT

Bugs

Please report any bugs or feature requests to bug-cxc-data-visitor@rt.cpan.org or through the web interface at: https://rt.cpan.org/Public/Dist/Display.html?Name=CXC-Data-Visitor

Source

Source is available at

https://gitlab.com/djerius/cxc-data-visitor

and may be cloned from

https://gitlab.com/djerius/cxc-data-visitor.git

AUTHOR

Diab Jerius <djerius@cpan.org>

COPYRIGHT AND LICENSE

This is free software, licensed under:

The GNU General Public License, Version 3, June 2007

To install CXC::Data::Visitor, copy and paste the appropriate command in to your terminal.

cpanm

cpanm CXC::Data::Visitor

CPAN shell

perl -MCPAN -e shell
install CXC::Data::Visitor

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)