Страницы справочника OS X

Эта страница руководства для  версии 10.9 Mac OS X

Читать страницы руководства

Hierarchy(3)                         User Contributed Perl Documentation                        Hierarchy(3)



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



perl v5.16.2                                     2006-11-04                                     Hierarchy(3)