Data::Hierarchy - Handle data in a hierarchical structure
my $tree = Data::Hierarchy->new();
$tree->store ('/', {access => 'all'});
$tree->store ('/private', {access => 'auth',
'.note' => 'this is private});
$info = $tree->get ('/private/somewhere/deep');
# return actual data points in list context
($info, @fromwhere) = $tree->get ('/private/somewhere/deep');
my @items = $tree->find ('/', {access => qr/.*/});
# override all children
$tree->store ('/', {'.note' => undef}, {override_sticky_descendents => 1});
Data::Hierarchy provides a simple interface for manipulating inheritable data
attached to a hierarchical environment (like a filesystem).
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":
$tree->store('/some/path', {'.color' => 'blue'});
print $tree->get('/some/path')->{'.color'}; # prints blue
print $tree->get('/some/path/below/that')->{'.color'}; # undefined
Note that you do not need to (and in fact, cannot) explicitly add
"files" or "directories" to the hierarchy; you simply
add and delete properties to paths.
Creates a new hierarchy object. Takes the following options:
- sep
- The string used as a separator between path levels. Defaults to '/'.
- "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.)
Chia-liang Kao <clkao@clkao.org> David Glasser <glasser@mit.edu>
Copyright 2003-2006 by Chia-liang Kao <clkao@clkao.org>.
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
See <http://www.perl.com/perl/misc/Artistic.html>