Data::Hierarchy(3) Handle data in a hierarchical structure


Instance Methods

"store $path, $properties, {%options}"
Given a path and a hash reference of properties, stores the properties at the path.

Unless the "override_descendents" option is given with a false value, it eliminates any non-sticky property in a descendent of $path with the same name.

If the "override_sticky_descendents" option is given with a true value, it eliminates any sticky property in a descendent of $path with the same name. override it.

A value of undef removes that value; note, though, that if an ancestor of $path defines that property, the ancestor's value will be inherited there; that is, with:

    $t->store('/a',   {k => 'top'});
    $t->store('/a/b', {k => 'bottom'});
    $t->store('/a/b', {k => undef});
    print $t->get('/a/b')->{'k'};

it will print 'top'.

"get $path, [$dont_clone]"
Given a path, looks up all of the properteies (sticky and not) and returns them in a hash reference. The values are clones, unless you pass a true value for $dont_clone.

If called in list context, returns that hash reference followed by all of the ancestral paths of $path which contain non-sticky properties (possibly including itself).

"find $path, $property_regexps"
Given a path and a hash reference of name/regular expression pairs, returns a list of all paths which are descendents of $path (including itself) and define at that path itself (not inherited) all of the properties in the hash with values matching the given regular expressions. (You may want to use "qr/.*/" to merely see if it has any value defined there.) Properties can be sticky or not.
"merge $other_hierarchy, $path"
Given a second Data::Hierarchy object and a path, copies all the properties from the other object at $path or below into the corresponding paths in the object this method is invoked on. All properties from the object this is invoked on at $path or below are erased first.
"to_relative $base_path"
Given a path which every element of the hierarchy must be contained in, returns a special Data::Hierarchy::Relative object which represents the hierarchy relative that path. The only thing you can do with a Data::Hierarchy::Relative object is call "to_absolute($new_base_path)" on it, which returns a new Data::Hierarchy object at that base path. For example, if everything in the hierarchy is rooted at "/home/super_project" and it needs to be moved to "/home/awesome_project", you can do

    $hierarchy = $hierarchy->to_relative('/home/super_project')->to_absolute('/home/awesome_project');

(Data::Hierarchy::Relative objects may be a more convenient serialization format than Data::Hierarchy objects, if they are tracking the state of some relocatable resource.)