1Hierarchy(3)          User Contributed Perl Documentation         Hierarchy(3)
2
3
4

NAME

6       Data::Hierarchy - Handle data in a hierarchical structure
7

SYNOPSIS

9           my $tree = Data::Hierarchy->new();
10           $tree->store ('/', {access => 'all'});
11           $tree->store ('/private', {access => 'auth',
12                                      '.note' => 'this is private});
13
14           $info = $tree->get ('/private/somewhere/deep');
15
16           # return actual data points in list context
17           ($info, @fromwhere) = $tree->get ('/private/somewhere/deep');
18
19           my @items = $tree->find ('/', {access => qr/.*/});
20
21           # override all children
22           $tree->store ('/', {'.note' => undef}, {override_sticky_descendents => 1});
23

DESCRIPTION

25       Data::Hierarchy provides a simple interface for manipulating
26       inheritable data attached to a hierarchical environment (like a
27       filesystem).
28
29       One use of Data::Hierarchy is to allow an application to annotate paths
30       in a real filesystem in a single compact data structure. However, the
31       hierarchy does not actually need to correspond to an actual filesystem.
32
33       Paths in a hierarchy are referred to in a Unix-like syntax; "/" is the
34       root "directory". (You can specify a different separator character than
35       the slash when you construct a Data::Hierarchy object.)  With the
36       exception of the root path, paths should never contain trailing
37       slashes. You can associate properties, which are arbitrary name/value
38       pairs, with any path.  (Properties cannot contain the undefined value.)
39       By default, properties are inherited by child paths: thus, if you store
40       some data at "/some/path":
41
42           $tree->store('/some/path', {color => 'red'});
43
44       you can fetch it again at a "/some/path/below/that":
45
46           print $tree->get('/some/path/below/that')->{'color'};
47           # prints red
48
49       On the other hand, properties whose names begin with dots are
50       uninherited, or "sticky":
51
52           $tree->store('/some/path', {'.color' => 'blue'});
53           print $tree->get('/some/path')->{'.color'};            # prints blue
54           print $tree->get('/some/path/below/that')->{'.color'}; # undefined
55
56       Note that you do not need to (and in fact, cannot) explicitly add
57       "files" or "directories" to the hierarchy; you simply add and delete
58       properties to paths.
59

CONSTRUCTOR

61       Creates a new hierarchy object.  Takes the following options:
62
63       sep The string used as a separator between path levels. Defaults to
64           '/'.
65

METHODS

67   Instance Methods
68       "store $path, $properties, {%options}"
69           Given a path and a hash reference of properties, stores the
70           properties at the path.
71
72           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
76           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
80           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
84               $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
89           it will print 'top'.
90
91       "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
96           If called in list context, returns that hash reference followed by
97           all of the ancestral paths of $path which contain non-sticky
98           properties (possibly including itself).
99
100       "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
103           (including itself) and define at that path itself (not inherited)
104           all of the properties in the hash with values matching the given
105           regular expressions.  (You may want to use "qr/.*/" to merely see
106           if it has any value defined there.)  Properties can be sticky or
107           not.
108
109       "merge $other_hierarchy, $path"
110           Given a second Data::Hierarchy object and a path, copies all the
111           properties from the other object at $path or below into the
112           corresponding paths in the object this method is invoked on.  All
113           properties from the object this is invoked on at $path or below are
114           erased first.
115
116       "to_relative $base_path"
117           Given a path which every element of the hierarchy must be contained
118           in, returns a special Data::Hierarchy::Relative object which
119           represents the hierarchy relative that path. The only thing you can
120           do with a Data::Hierarchy::Relative object is call
121           "to_absolute($new_base_path)" on it, which returns a new
122           Data::Hierarchy object at that base path. For example, if
123           everything in the hierarchy is rooted at "/home/super_project" and
124           it needs to be moved to "/home/awesome_project", you can do
125
126               $hierarchy = $hierarchy->to_relative('/home/super_project')->to_absolute('/home/awesome_project');
127
128           (Data::Hierarchy::Relative objects may be a more convenient
129           serialization format than Data::Hierarchy objects, if they are
130           tracking the state of some relocatable resource.)
131

AUTHORS

133       Chia-liang Kao <clkao@clkao.org> David Glasser <glasser@mit.edu>
134
136       Copyright 2003-2006 by Chia-liang Kao <clkao@clkao.org>.
137
138       This program is free software; you can redistribute it and/or modify it
139       under the same terms as Perl itself.
140
141       See <http://www.perl.com/perl/misc/Artistic.html>
142
143
144
145perl v5.28.1                      2006-11-05                      Hierarchy(3)
Impressum