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