DESCRIPTION

One use of Data::Hierarchy is to allow an application to annotate paths in a real filesystem in a single compact data structure. However, the hierarchy does not actually need to correspond to an actual filesystem.

Paths in a hierarchy are referred to in a Unix-like syntax; "/" is the root "directory". (You can specify a different separator character than the slash when you construct a Data::Hierarchy object.) With the exception of the root path, paths should never contain trailing slashes. You can associate properties, which are arbitrary name/value pairs, with any path. (Properties cannot contain the undefined value.) By default, properties are inherited by child paths: thus, if you store some data at /some/path:

$tree->store('/some/path', {color => 'red'});

you can fetch it again at a /some/path/below/that:

print $tree->get('/some/path/below/that')->{'color'};
# prints red

On the other hand, properties whose names begin with dots are uninherited, or "sticky":

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