Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 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.24.1			  2006-11-05			  Hierarchy(3)

NAME | SYNOPSIS | DESCRIPTION | CONSTRUCTOR | METHODS | AUTHORS | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Data::Hierarchy&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help