/ 
Hash-DotPath-0.002
River stage one • 1 direct dependent • 1 total dependent
/ Hash::DotPath

NAME

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

VERSION

version 0.002

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', []); 
$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;

ARRAYS

You interact with array elements slightly differently than hash ones.

To access an element in an array, use the numeric index in the path.

$dot = Hash::DotPath->new({foo => ['a', 'b', 'c']});
$dot->get('foo.0');

To set a value on an existing array, the same notation works.

$dot->set('foo.3', 'd');

To add a NEW array to the tree, you must first instantiate it. This is because hash keys can be numeric. Since this is a hash class, the default is to treat integers like hash keys unless a array already exists at the given location.

$dot = Hash::DotPath->new({ foo => 'bar'});

# WRONG - this is a non-existent array
$dot->set('biz.0', 'baz'); 

# CORRECT
$dot->set('biz', []);
$dot->set('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;