Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  DATA::HIERARCHY (3)

.ds Aq ’


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 ’/’.


    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 <B>at that path itselfB> (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 <B>everyB> element of the hierarchy must be contained in, returns a special Data::Hierarchy::Relative object which represents the hierarchy relative that path. The <B>onlyB> 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 <> David Glasser <>


Copyright 2003-2006 by Chia-liang Kao <>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See <>

Search for    or go to Top of page |  Section 3 |  Main Index

perl v5.20.3 HIERARCHY (3) 2006-11-05

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.