home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2007 September / PCWSEP07.iso / Software / Linux / Linux Mint 3.0 Light / LinuxMint-3.0-Light.iso / casper / filesystem.squashfs / usr / share / perl5 / Data / Grove.pm
Encoding:
Perl POD Document  |  2003-10-21  |  3.4 KB  |  121 lines
  1. #
  2. # Copyright (C) 1999 Ken MacLeod
  3. # Data::Grove is free software; you can redistribute it and/or
  4. # modify it under the same terms as Perl itself.
  5. #
  6. # $Id: Grove.pm,v 1.6 1999/12/22 21:15:00 kmacleod Exp $
  7. #
  8.  
  9. ###
  10. ### For a similar package, see also:
  11. ###
  12. ###   Graph::Element -- elements for a directed graph
  13. ###     Neil Bowers <neilb@cre.canon.co.uk> (NIELB)
  14. ### 
  15.  
  16. package Data::Grove;
  17.  
  18. use vars qw{ $VERSION };
  19.  
  20. # will be substituted by make-rel script
  21. $VERSION = "0.08";
  22.  
  23. sub new {
  24.     my $type = shift;
  25.     my $self = ($#_ == 0) ? { %{ (shift) } } : { @_ };
  26.  
  27.     if (defined $self->{Raw}) {
  28.     # clone the raw object
  29.     $self = { %{ $self->{Raw} } };
  30.     }
  31.  
  32.     return bless $self, $type;
  33. }
  34.  
  35. package Data::Grove::Characters;
  36. use vars qw{ @ISA $type_name };
  37. @ISA = qw{Data::Grove};
  38. $type_name = 'characters';
  39.  
  40. 1;
  41.  
  42. __END__
  43.  
  44. =head1 NAME
  45.  
  46. Data::Grove -- support for deeply nested structures
  47.  
  48. =head1 SYNOPSIS
  49.  
  50.  use Data::Grove;
  51.  
  52.  $object = MyPackage->new;
  53.  
  54.  package MyPackage;
  55.  @ISA = qw{Data::Grove};
  56.  
  57. =head1 DESCRIPTION
  58.  
  59. C<Data::Grove> provides support for deeply nested tree or graph
  60. structures.  C<Data::Grove> is intended primarily for Perl module
  61. authors writing modules with many types or classes of objects that
  62. need to be manipulated and extended in a consistent and flexible way.
  63.  
  64. C<Data::Grove> is best used by creating a core set of ``data'' classes
  65. and then incrementally adding functionality to the core data classes
  66. by using ``extension'' modules.  One reason for this design is so that
  67. the data classes can be swapped out and the extension modules can work
  68. with new data sources.  For example, these other data sources could be
  69. disk-based, network-based or built on top of a relational database.
  70.  
  71. Two extension modules that come with C<Data::Grove> are
  72. C<Data::Grove::Parent> and C<Data::Grove::Visitor>.
  73. C<Data::Grove::Parent> adds a `C<Parent>' property to grove objects
  74. and implements a `C<root>' method to grove objects to return the root
  75. node of the tree from anywhere in the tree and a `C<rootpath>' method
  76. to return a list of nodes between the root node and ``this'' node.
  77. C<Data::Grove::Visitor> adds callback methods `C<accept>' and
  78. `C<accept_name>' that call your handler or receiver module back by
  79. object type name or the object's name.
  80.  
  81. C<Data::Grove> objects do not contain parent references, Perl garbage
  82. collection will delete them when no longer referenced and
  83. sub-structures can be shared among several structures.
  84. C<Data::Grove::Parent> is used to create temporary objects with parent
  85. pointers.  
  86.  
  87. Properties of data classes are accessed directly using Perl's hash
  88. functions (i.e. `C<$object-E<gt>{Property}>').  Extension modules may
  89. also define properties that they support or use, for example
  90. Data::Grove::Parent adds `C<Parent>' and `C<Raw>' properties and
  91. Visitor depends on `C<Name>' and `C<Content>' properties.
  92.  
  93. See the module C<XML::Grove> for an example implementation of
  94. C<Data::Grove>.
  95.  
  96. =head1 METHODS
  97.  
  98. =over 4
  99.  
  100. =item new( PROPERTIES )
  101.  
  102. Return a new object blessed into the SubClass, with the given
  103. properties.  PROPERTIES may either be a list of key/value pairs, a
  104. single hash containing key/value pairs, or an existing C<Data::Grove>
  105. object.  If an existing C<Data::Grove> is passed to `C<new()>', a
  106. shallow copy of that object will be returned.  A shallow copy means
  107. that you are returned a new object, but all of the objects underneath
  108. still refer to the original objects.
  109.  
  110. =back
  111.  
  112. =head1 AUTHOR
  113.  
  114. Ken MacLeod, ken@bitsko.slc.ut.us
  115.  
  116. =head1 SEE ALSO
  117.  
  118. perl(1)
  119.  
  120. =cut
  121.