The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
CXC-Data-Visitor-0.02
River stage zero No dependents
/ CXC::Data::Visitor

NAME

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

VERSION

version 0.02

SYNOPSIS

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

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

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

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.

  • 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, invoke $callback on every element (hash entry or array element) in $struct. $callback is invoked on a container first before being called on its elements. Blessed hashes or arrays are not traversed. Cycles are detected, but nodes which are accessible from multiple parents are visited more than once.

For example, if

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

The calling order is

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

The values returned are:

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

%opts may contain the following entries:

context => hashref

A reference to a hash which is passed to "$callback". It defaults to a freshly created hash.

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

How to handle cycles in the data structure (the constants are available for import; see "EXPORTS"). Cycles are detected upon traversing a node a second time in a depth first search.

Note that a node can be reached multiple times without cycling, for example, this is not a cycle:g

%hash = ( a => { b => [ 0, 1 ] }, );
$hash{c} = $hash{a};

Acceptable values are:

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

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

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

$cycle should be one of CYCLE_DIE, CYCLE_CONTINUE, or CYCLE_TRUNCATE, and indicates what should be done.

visit VISIT_CONTAINER, VISIT_LEAF, VISIT_ALL

The parts of the structure will trigger a callback (the constants are available for import; see "EXPORTS").

Acceptable values are:

VISIT_CONTAINER

Only containers get a callback. For example, the elements in the following structure

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

which will be passed to "$callback" are:

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

Only containers get a callback. For example, the elements in the following structure

For example, the following structure

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

which will be passed to "$callback" are:

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

All elements get a callback. Default

$callback will be called as:

$continue = $callback->( $kydx, $vref, $context, $metadata );

and should return true if the process of visiting elements should continue, false if "visit" should return immediately.

Its arguments are

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

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

The following export tags are available:

-all

Import all symbols

-constants

Import the following symbols

VISIT_CONTAINER VISIT_LEAF VISIT_ALL
CYCLE_DIE CYCLE_CONTINUE CYCLE_TRUNCATE

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

SEE ALSO

Please see those modules/websites for more information related to this module.

AUTHOR

Diab Jerius <djerius@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2024 by Smithsonian Astrophysical Observatory.

This is free software, licensed under:

The GNU General Public License, Version 3, June 2007