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

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 "die"s 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

"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.