---
name: "Data::Hierarchy"
section: "3pm"
platform: "linux"
package: "perl-data-hierarchy"
version: "0.34-18"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/Data::Hierarchy"
---

# Data::Hierarchy(3pm)

Handle data in a hierarchical structure

## NAME

Data::Hierarchy - Handle data in a hierarchical structure

## SYNOPSIS

```
    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});
```

## DESCRIPTION

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.

## CONSTRUCTOR

Creates a new hierarchy object.  Takes the following options:

- sep

  The string used as a separator between path levels. Defaults to '/'.

## METHODS

### 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.)

## AUTHORS

Chia-liang Kao \<clkao@clkao.org\> David Glasser \<glasser@mit.edu\>

## COPYRIGHT

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\>