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