/ 
Data-Diver-1.0101
River stage one • 8 direct dependents • 8 total dependents
/ Data::Diver

NAME

Data::Diver - 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" doesn't 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" isn't 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 "Couldn't dereference $nestedRef via $$svKey: $errDesc\n";
}

DESCRIPTION

Note that Data::Diver does use strict; and so will not use symbolic references. That is, a simple string can never be used as a reference.

Dive

$value= Dive( $root, @ListOfKeys )

Dive() pulls out one value from a nested data structure.

Dive() absolutely refuses to autovivify anything. If you give any 'key' that would require autovivification [or would cause an error or warning], then an empty list is returned.

How Dive() works is easiest to "explain" by looking at the examples listed in the "SYNOPSIS" section above.

$root should be a reference, usually a reference to hash or to an array. @ListOfKeys should be a list of values to use as hash keys or array indices [or a few other things] that will be used to deference deeper and deeper into the data structure that $root refers to.

More details can be found under "Simple 'key' values" and "Advanced 'key' values" further down.

If you want to distinguish between exists and defined for a hash element, then you can distinguish between an empty list, ( ), being returned and one undef, ( undef ), being returned:

my @exists= Dive( \%hashOfHashes, 'first', 'second' );
if(  ! @exists  ) {
    warn "\$hashOfHashes{first}{second} does not exists.\n";
} elsif(  ! defined $exists[0]  ) {
    warn "\$hashOfHashes{first}{second} exists but is undefined.\n";
}

DiveVal

$val= DiveVal( $root, @ListOfKeys );

DiveVal( $root, @ListOfKeys )= $val;

DiveVal() is very much like Dive() except that it autovivifies if it can, dies if it can't, and is an LValue subroutine. So you can assign to DiveVal() and the dereferenced element will be modified. You can also take a reference to the call to DiveVal() or do anything else that you can do with a regular scalar variable.

If $root is undefined, then DiveVal() immediately returns ( undef ) [without overwriting DiveError()]. This is for the special case of using DiveVal( Dive( ... ), ... ) because you want to only allow partial autovivifying.

DiveRef

$ref= DiveRef( $root, @ListOfKeys )

Simple 'key' values

Both Dive() and DiveRef() start by trying to dereference $root using the first element of @ListOfKeys. We refer to the resulting value as $ref and, if there are more elements in @ListOfKeys, then the next step will be to try to dereference $ref using that next 'key' [producing a new value for $ref].

To dereference an array reference, you must give a 'key' value that is defined and matches m/^-?\d+$/. So, if you have more general numeric values, you should use int() to convert them to simple integers.

To dereference a hash reference, you must give a 'key' value that is defined (or that is a reference to a scalar that will be used as the key).

Note that all 'keys' that work for arrays also work for hashes. If you have a reference that is overloaded such that it can both act as an array reference and as a hash reference [or, in the case of DiveVal() and DiveRef(), if you have an undefined $ref which can be autovivified into either type of reference], then numeric-looking key values cause an array dereference. In the above cases, if you want to do a hash dereference, then you need to pass in a reference to the key.

Note that undefined keys are reserved for a special meaning discussed in "Advanced 'key' values" further down. That section discusses how to dereference other types of references [scalar references and subroutine references] and exactly how the different reference types and key values interact.

DiveError

( $errDesc, $ref, $svKey )= DiveError();

In the case of Dive() returning an empty list, a subsequent call to DiveError() will return a description of why Dive() failed, the specific reference that was trying to be dereferenced [not just the top-level $root reference that was passed into Dive], and a reference to the specific 'key'.

DiveClear

DiveClear();

DiveClear() erases the record of any previous Dive() failures.

DiveDie

DiveDie();

or

$value= DiveDie( Dive(...) );

or

$value= DiveDie( $root, @ListOfKeys );

This dies with an error message based on the previously saved Dive() failure reason.

If there is no previously saved failure reason or if one argument is passed into DiveDie(), then it simply returns that argument [or an empty list].

If more than one argument is passed into DiveDie(), then those arguments are passed to Dive() and then DiveDie() behaves as described above. That is, DiveDie($root,@list) acts the same as DiveDie(Dive($root,@list)).

Advanced 'key' values

For both Dive() and DiveRef(), each $key in @ListOfKeys can have the following values:

undef

This means that you expect $ref to be a reference to a scalar and you want to dereference it.

For Dive(), if $ref is undefined or is something that can't act as a reference to a scalar, then the empty list is returned and DiveError() can tell you where the problem was.

For DiveRef(), if $ref is undef, then it will be autovivified into a reference to a scalar [that will start out undefined but may quickly become autovivified due to the next element of @ListOfKeys]. If $ref is something that can't act as a scalar reference, then Perl will die to tell you why.

Otherwise the scalar ref is deferenced ($$ref) and we continue on to the next element of @ListOfKeys.

a reference to a scalar

This means that you expect $ref to be a reference to a hash and you want to dereference it using $$key as the key.

This is most useful for when you want to use hash keys that match m/^-?\d+$/. Note that \( listOfScalars ) will give you a list of references to those scalars so you can often just add \( and ) around your list of keys if you only want to do hash dereferencing:

DiveVal( $ref, \( 1, -5, qw< 00 01 >, list(), 1-9, 0xFF ) )= 9;

But, if your argument list of key values is build out of at least one array and any other item, then it won't work since:

\( @a, $b, 9 ) is ( \@a, \$b, \9 )

so you'll need to either wrap each array in additional parens or use map:

\( (@a), $b, (@c), 9 )

map \$_, @a, $b, @c, 9
$key =~ m/^-?\d+$/

This means that you might expect $ref to be a reference to an array.

For Dive(), if $ref can act as a reference to an array and $key is in range ( -@$ref <= $key and $key <= $#$ref ), then $ref= $ref->[$key]; is run [and this can't fail nor autovivify since we've already checked how big that array was].

If $ref can't be used as an array reference, then $ref might be used as a hash reference instead, as described further down.

If $ref is undefined or $key is out of range ($key < -@$ref or $#$ref < $key), then Dive() returns an empty list.

For DiveRef(), if $ref is undefined, then it is autovivified into a reference to anonymous array. If $ref can act as a reference to an array, then $ref= $ref->[$key] is attempted. If $key is larger than $#$ref, then @$ref will grow. If $key is less than -@$ref, then Perl will die.

If $ref cannot act as a reference to an array, then $ref might be used as a reference to a hash as described further down.

a reference to an array

If $key can be used as a reference to an array, then it means that you might expect $ref to be a reference to a subroutine.

If UNIVERSAL::isa( $ref, 'CODE' ) is true, then $ref->( @$key ) is attempted.

If $key isn't the last value in @ListOfKeys and the next value is undefined, then &$ref is called in a scalar context and $ref is set to refer to the scalar value returned.

Otherwise, &$ref is called in a list context and $ref is set to refer to an anonymous array containing the value(s) returned.

any (defined) string

This means that you might expect $ref to be a reference to a hash.

For Dive(), if $ref can act as a reference to a hash and <exists $ref-{$key} >> is true, then $ref= $ref->{$key}; is run [and this can't fail nor autovivify].

Otherwise, Dive() returns an empty list and DiveError() can tell you where the problem was.

For DiveRef(), $ref= $ref->{$key} is simply attempted. This may autovivify a hash entry or even a new hash. It may also die, for example, if $ref can't be used as a hash reference.

Note that the order of the above items is significant. It represents the order in which cases are tested. So an undefined $key will only be for derefencing a scalar reference and a numeric key will prefer to treat a reference as an array reference.

AUTHOR

Tye McQueen, http://www.perlmonks.org/?node=tye

SEE ALSO

Once More With Feeling -- Joss++