NAME

Hash::DotPath - Class for manipulating hashes via dot path notation.

VERSION

version 0.004

SYNOPSIS

$dot = Hash::DotPath->new;
$dot = Hash::DotPath->new(\%myhash);
$dot = Hash::DotPath->new(\%myhash, delimiter => '~');

$val = $dot->get('foo.bar');
$val = $dot->get('biz.baz.0.zoo');  

$dot->set('foo', 'bar');
$dot->set('cats.0', 'calico');

$dot->delete('foo');

$newObj = $dot->merge({ biz => 'baz' });
$newObj = $dot->merge({ biz => 'other' }, 'RIGHT'); 

%hash = $dot->toHash;
$href = $dot->toHashRef;  

ARRAY vs HASH vivification

When assigning a value to a path where a non-existent segment of the path is an integer, an array reference will be vivified at that position. If you wish to have a hash reference in its place, you must instantiate it manually in advance. For example:

 # Assuming biz isn't defined yet, this will set biz to an array reference.
 
 $dot = Hash::DotPath->new;
 $dot->set('biz.0', 'baz'); 
 Data::Printer::p($dot->toHashRef); 

 {
     biz   [
         [0] "baz"
     ]
 }

 # In order to set biz to a hash reference you must instantiate it first.
 
 $dot->set('biz', {});
 $dot->set('biz.0', 'baz');
 Data::Printer::p($dot->toHashRef); 

 {
     biz   {
         0   "baz"
     }
 }
   

ATTRIBUTES

delimiter [Str] (optional)

The delimiter to use when analyzing a dot path.

Default: "."

METHODS

delete

Deletes an element at the specified path. Returns the value of the element that was deleted.

usage:

$val = $dot->delete('foo.bar');
$val = $dot->delete('biz.0.baz');

args:

path [Str]

Dot-path of the element you wish to delete.

get

Gets an element at the specified path. Returns 'Any'.

usage:

$val = $dot->get('foo.bar');
$val = $dot->get('biz.0.baz');

args:

path [Str]

Dot-path of the element you wish to get.

exists

Determines if an element exists at the given path. Returns 'Bool'.

usage:

$bool = $dot->exists('foo.bar');
$bool = $dot->exists('biz.0.baz');

args:

path [Str]

Dot-path of the element you wish to get.

merge

Merges the provided dot-path object or hashref with the object. You indicate which hash has precedence by providing the 'overwrite' arg.

usage:

$newDot = $dot->merge({foo => 'bar'}, [0|1]);

$dot2 = Hash::DotPath->new(biz => 'baz');
$newDot = $dot->merge($dot2, [0|1]);
 

args:

merge [HashRef|Hash::DotPath]

Hashref you wish to merge into the dot-path object.

overwrite [Bool] (optional)

Indicates which hash has precedence over the other. A true value means the element passed in will overwrite any pre-existing elements. A false value will preserve existing elements and just merge the new ones in.

Default: 1

set

Sets an element at the specified path. Returns the value that was passed in.

usage:

$val = $dot->set('foo.bar', 'abc');
$val = $dot->set('biz.0.baz', 'def');

args:

path [Str]

Dot-path of the element you wish to set.

value [Any]

Value you wish to set at the given path.

toHash

Returns a hash version of the object.

usage:

%hash = $dot->toHash;

toHashRef

Returns a hashref version of the object.

usage:

$href = $dot->toHashRef;

cpanm Hash::DotPath

perl -MCPAN -e shell
install Hash::DotPath