Data::Diver 1.0101

Data::Diver is a simple, ad-hoc access to elements of deeply nested structures.

SUMMARY

Data::Diver provides the Dive() and DiveVal() functions for ad-hoc access to elements of deeply nested data structures, and the DiveRef(), DiveError(), DiveClear(), and DiveDie() support functions.

SYNOPSIS

use Data::Diver qw( Dive DiveRef DiveError );

my $root= {
top => [
{ first => 1 },
{ second => {
key => [
0, 1, 2, {
three => {
exists => yes,
},
},
],
},
},
],
};

# Sets $value to yes
# ( $root->{top}[1]{second}{key}[3]{three}{exists} ):
my $value= Dive( $root, qw( top 1 second key 3 three exists ) );

# Sets $value to undef() because "missing" doesnt exist:
$value= Dive( $root, qw( top 1 second key 3 three missing ) );

# Sets $value to undef() because
# $root->{top}[1]{second}{key}[4] is off the end of the array:
$value= Dive( $root, qw( top 1 second key 4 ... ) );

# Sets $value to undef() because
# $root->{top}[1]{second}{key}[-5] would be a fatal error:
$value= Dive( $root, qw( top 1 second key -5 ... ) );

# Sets $ref to $root->{top}[9]{new}{sub} (which grows
# @{ $root->{top} } and autovifies two anonymous hashes):
my $ref= DiveRef( $root, qw( top 9 new sub ) );

# die()s because "other" isnt a valid number:
$ref= DiveRef( $root, qw( top other ... ) );

# Does: $root->{num}{1}{2}= 3;
# (Autovivifies hashes despite the numeric keys.)
DiveVal( $root, ( qw( num 1 2 ) ) ) = 3;
# Same thing:
${ DiveRef( $root, num, 1, 2 ) } = 3;

# Retrieves above value, $value= 3:
$value= DiveVal( $root, num, 1, 2 );
# Same thing:
$value= ${ DiveRef( $root, ( qw( num 1 2 ) ) ) };

# Tries to do $root->{top}{1} and dies
# because $root->{top} is an array reference:
DiveRef( $root, top, 1 );

# To only autovivify at the last step:
$ref= DiveRef(
Dive( $root, qw( top 1 second key 3 three ) ),
missing );
if( $ref ) {
$$ref= me too
} else {
my( $nestedRef, $svKey, $errDesc )= DiveError();
die "Couldnt dereference $nestedRef via $$svKey: $errDescn";
}