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.

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.

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.

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

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

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.

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:

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.

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.