1Hierarchy(3) User Contributed Perl Documentation Hierarchy(3)
2
6 Data::Hierarchy - Handle data in a hierarchical structure
7
9 my $tree = Data::Hierarchy->new();
10 $tree->store ('/', {access => 'all'});
11 $tree->store ('/private', {access => 'auth',
12 '.note' => 'this is private});
13 $info = $tree->get ('/private/somewhere/deep');
15 # return actual data points in list context
17 ($info, @fromwhere) = $tree->get ('/private/somewhere/deep');
18 my @items = $tree->find ('/', {access => qr/.*/});
20 # override all children
22 $tree->store ('/', {'.note' => undef}, {override_sticky_descendents => 1});
23
25 Data::Hierarchy provides a simple interface for manipulating inherita‐
26 ble data attached to a hierarchical environment (like a filesystem).
27 One use of Data::Hierarchy is to allow an application to annotate paths
29 in a real filesystem in a single compact data structure. However, the
30 hierarchy does not actually need to correspond to an actual filesystem.
31 Paths in a hierarchy are referred to in a Unix-like syntax; "/" is the
33 root "directory". (You can specify a different separator character than
34 the slash when you construct a Data::Hierarchy object.) With the
35 exception of the root path, paths should never contain trailing
36 slashes. You can associate properties, which are arbitrary name/value
37 pairs, with any path. (Properties cannot contain the undefined value.)
38 By default, properties are inherited by child paths: thus, if you store
39 some data at "/some/path":
40 $tree->store('/some/path', {color => 'red'});
42 you can fetch it again at a "/some/path/below/that":
44 print $tree->get('/some/path/below/that')->{'color'};
46 # prints red
47 On the other hand, properties whose names begin with dots are uninher‐
49 ited, or "sticky":
50 $tree->store('/some/path', {'.color' => 'blue'});
52 print $tree->get('/some/path')->{'.color'}; # prints blue
53 print $tree->get('/some/path/below/that')->{'.color'}; # undefined
54 Note that you do not need to (and in fact, cannot) explicitly add
56 "files" or "directories" to the hierarchy; you simply add and delete
57 properties to paths.
58
60 Creates a new hierarchy object. Takes the following options:
61 sep The string used as a separator between path levels. Defaults to
63 '/'.
64
66 Instance Methods
67 "store $path, $properties, {%options}"
69 Given a path and a hash reference of properties, stores the proper‐
70 ties at the path.
71 Unless the "override_descendents" option is given with a false
73 value, it eliminates any non-sticky property in a descendent of
74 $path with the same name.
75 If the "override_sticky_descendents" option is given with a true
77 value, it eliminates any sticky property in a descendent of $path
78 with the same name. override it.
79 A value of undef removes that value; note, though, that if an
81 ancestor of $path defines that property, the ancestor's value will
82 be inherited there; that is, with:
83 $t->store('/a', {k => 'top'});
85 $t->store('/a/b', {k => 'bottom'});
86 $t->store('/a/b', {k => undef});
87 print $t->get('/a/b')->{'k'};
88 it will print 'top'.
90 "get $path, [$dont_clone]"
92 Given a path, looks up all of the properteies (sticky and not) and
93 returns them in a hash reference. The values are clones, unless
94 you pass a true value for $dont_clone.
95 If called in list context, returns that hash reference followed by
97 all of the ancestral paths of $path which contain non-sticky prop‐
98 erties (possibly including itself).
99 "find $path, $property_regexps"
101 Given a path and a hash reference of name/regular expression pairs,
102 returns a list of all paths which are descendents of $path (includ‐
103 ing itself) and define at that path itself (not inherited) all of
104 the properties in the hash with values matching the given regular
105 expressions. (You may want to use "qr/.*/" to merely see if it has
106 any value defined there.) Properties can be sticky or not.
107 "merge $other_hierarchy, $path"
109 Given a second Data::Hierarchy object and a path, copies all the
110 properties from the other object at $path or below into the corre‐
111 sponding paths in the object this method is invoked on. All prop‐
112 erties from the object this is invoked on at $path or below are
113 erased first.
114 "to_relative $base_path"
116 Given a path which every element of the hierarchy must be contained
117 in, returns a special Data::Hierarchy::Relative object which repre‐
118 sents the hierarchy relative that path. The only thing you can do
119 with a Data::Hierarchy::Relative object is call "to_abso‐
120 lute($new_base_path)" on it, which returns a new Data::Hierarchy
121 object at that base path. For example, if everything in the hierar‐
122 chy is rooted at "/home/super_project" and it needs to be moved to
123 "/home/awesome_project", you can do
124 $hierarchy = $hierarchy->to_relative('/home/super_project')->to_absolute('/home/awesome_project');
126 (Data::Hierarchy::Relative objects may be a more convenient serial‐
128 ization format than Data::Hierarchy objects, if they are tracking
129 the state of some relocatable resource.)
130
132 Chia-liang Kao <clkao@clkao.org> David Glasser <glasser@mit.edu>
133
135 Copyright 2003-2006 by Chia-liang Kao <clkao@clkao.org>.
136 This program is free software; you can redistribute it and/or modify it
138 under the same terms as Perl itself.
139 See <http://www.perl.com/perl/misc/Artistic.html>
141perl v5.8.8 2006-11-05 Hierarchy(3)