Data-Reach

Data::Reach - Walk down or iterate through a nested Perl datastructure

=head1 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

=head1 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 L<perldsc>. Walking down through such
structures usually involves nested loops, and possibly some tests on
C<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 :

=over

=item *

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

=item *

the C<map_paths> function applies a given code reference to all paths within the nested
datastructure.


=item *

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

=back



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:

L<http://www.perlfoundation.org/artistic_license_2_0>