SYNOPSIS

    # reach a subtree or a leaf under a nested datastructure
    use Data::Reach;
    my $node = reach $data_tree, @path; # @path may contain a mix of hash keys and array indices

    # do something with all paths through the datastructure ..
    my @result = map_paths {do_something_with(\@_, $_)} $data_tree;

    # .. or loop through all paths
    my $next_path = each_path $data_tree;
    while (my ($path, $val) = $next_path->()) {
      do_something_with($path, $val);
    }

    # import under a different name
    use Data::Reach reach => as => 'walk_down';
    my $node = walk_down $data_tree, @path;

    # optional changes of algorithm, lexically scoped
    { no Data::Reach  qw/peek_blessed use_overloads/;
      use Data::Reach reach_method => [qw/foo bar/];
      my $node = reach $object_tree, @path;
    }
    # after end of scope, back to the regular algorithm

DESCRIPTION

Perl supports nested datastructures : a hash may contain references to other hashes or to arrays, which in turn may contain further references to deeper structures -- see perldsc. Walking down through such structures usually involves nested loops, and possibly some tests on ref $subtree for finding out if the next level is an arrayref or a hashref.

The present module offers some utilities for easier handling of nested datastructures :

• the reach function finds a subtree or a leaf according to a given @path -- a list of hash keys or array indices. If there is no data corresponding to that path, undef is returned, without any autovivification within the tree.

• the map_paths function applies a given code reference to all paths within the nested datastructure.

• the each_path function returns an iterator over the nested datastructure; it can be used in the same spirit as an each statement over a simple hash, except that it will walk through all paths within the nested datastructure

INSTALLATION

To install this module, run the following commands:

        perl Build.PL
        perl Build
        perl Build test
        perl Build install

SUPPORT AND DOCUMENTATION

After installing, you can find documentation for this module with the perldoc command.

    perldoc Data::Reach

You can also look for information at:

    https://metacpan.org/pod/Data::Reach

LICENSE AND COPYRIGHT

Copyright (C) 2015, 2022 Laurent Dami

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0