local-lib5/lib/perl5/Tree/Simple/VisitorFactory.pm

   1
   2 package Tree::Simple::VisitorFactory;
   3
   4 use strict;
   5 use warnings;
   6
   7 our $VERSION = '0.10';
   8
   9 sub new {
  10     my ($class) = @_;
  11     return bless \$class;
  12 }
  13
  14 sub get {
  15     my ($class, $visitor) = @_;
  16     (defined($visitor)) || die "Insufficient Arguments : You must specify a Visitor to load";
  17     $visitor = "Tree::Simple::Visitor::$visitor";
  18     eval "require $visitor";
  19     die "Illegal Operation : Could not load Visitor ($visitor) because $@" if $@;
  20     return $visitor->new();
  21 }
  22
  23 *getVisitor = \&get;
  24
  25 1;
  26
  27 __END__
  28
  29 =head1 NAME
  30
  31 Tree::Simple::VisitorFactory - A factory object for dispensing Visitor objects
  32
  33 =head1 SYNOPSIS
  34
  35   use Tree::Simple::VisitorFactory;
  36
  37   my $tf = Tree::Simple::VisitorFactory->new();
  38
  39   my $visitor = $tf->get("PathToRoot");
  40
  41   # or call it as a class method
  42   my $visitor = Tree::Simple::VisitorFactory->getVisitor("PathToRoot");
  43
  44 =head1 DESCRIPTION
  45
  46 This object is really just a factory for dispensing Tree::Simple::Visitor::* objects. It is not required to use this package in order to use all the Visitors, it is just a somewhat convienient way to avoid having to type thier long class names.
  47
  48 I considered making this a Singleton, but I did not because I thought that some people might not want that. I know that I am very picky about using Singletons, especially in multiprocess environments like mod_perl, so I implemented the smallest instance I knew how to, and made sure all other methods could be called as class methods too.
  49
  50 =head1 METHODS
  51
  52 =over 4
  53
  54 =item B<new>
  55
  56 Returns an minimal instance of this object, basically just a reference back to the package (literally, see the source if you care).
  57
  58 =item B<get ($visitor_type)>
  59
  60 Attempts to load the C<$visitor_type> and returns an instance of it if successfull. If no C<$visitor_type> is specified an exception is thrown, if C<$visitor_type> fails to load, and exception is thrown.
  61
  62 =item B<getVisitor ($visitor_type)>
  63
  64 This is an alias of C<get>.
  65
  66 =back
  67
  68 =head1 AVAILABLE VISITORS
  69
  70 This distibution provides a number of Visitor objects which can be loaded just by giving their name. Below is a description of the available Visitors and a sort description of what they do. I have attempted to classify the Visitors into groups which are related to their use.
  71
  72 This factory will load any module contained inside the B<Tree::Simple::Visitor::*> namespace. Given a name, it will attempt to C<require> the module B<Tree::Simple::Visitor::E<lt>I<Name>E<gt>.pm>. This allows others to create Visitors which can be accessed with this factory, without needed to include them in this distrobution.
  73
  74 =head2 Search/Path Related Visitors
  75
  76 =over 4
  77
  78 =item B<PathToRoot>
  79
  80 Given a Tree::Simple object, this Visitor will find the path back to the tree's root node.
  81
  82 =item B<FindByPath>
  83
  84 Given a path and Tree::Simple hierarchy, this Visitor will attempt to find the node specified by the path.
  85
  86 =item B<FindByUID>
  87
  88 Given a UID and Tree::Simple hierarchy, this Visitor will attempt to find the node with the same UID.
  89
  90 =item B<FindByNodeValue>
  91
  92 Given a node value and Tree::Simple hierarchy, this Visitor will attempt to find the node with the same node value.
  93
  94 =back
  95
  96 =head2 Traversal Visitors
  97
  98 =over 4
  99
 100 =item B<BreadthFirstTraversal>
 101
 102 This implements a breadth-first traversal of a Tree::Simple hierarchy.
 103
 104 =item B<PostOrderTraversal>
 105
 106 Post-order traversal is a variation of the depth-first traversal in which the sub-tree's are processed I<before> the parent.
 107
 108 =item B<PreOrderTraversal>
 109
 110 Pre-order traversal is a depth-first traversal method in which the sub-tree's are processed I<after> the parent.
 111
 112 =back
 113
 114 =head2 FileSystem Visitors
 115
 116 =over 4
 117
 118 =item B<LoadDirectoryTree>
 119
 120 This visitor can be used to load a directory tree into a Tree::Simple hierarchy.
 121
 122 =item B<CreateDirectoryTree>
 123
 124 This visitor can be used to create a set of directories and files from a Tree::Simple object hierarchy.
 125
 126 =back
 127
 128 =head2 Conversion Visitors
 129
 130 =over 4
 131
 132 =item B<FromNestedArray>
 133
 134 Given a tree constructed from nested arrays, this Visitor will create the equivalent Tree::Simple heirarchy.
 135
 136 =item B<ToNestedArray>
 137
 138 Given a Tree::Simple heirarchy, this Visitor will create the equivalent tree constructed from nested arrays.
 139
 140 =item B<FromNestedHash>
 141
 142 Given a tree constructed from nested hashs, this Visitor will create the equivalent Tree::Simple heirarchy.
 143
 144 =item B<ToNestedHash>
 145
 146 Given a Tree::Simple heirarchy, this Visitor will create the equivalent tree constructed from nested hashes.
 147
 148 =back
 149
 150 =head2 Reflective Visitors
 151
 152 =over 4
 153
 154 =item B<LoadClassHierarchy>
 155
 156 Given a class name or instance, this Visitor will create a Tree::Simple hierarchy which models the classes inheritance heirarchy.
 157
 158 =back
 159
 160 =head2 Misc. Visitors
 161
 162 =over 4
 163
 164 =item B<GetAllDescendents>
 165
 166 Given a Tree::Simple instance this Visitor will return all the descendents recursively on down the hierarchy.
 167
 168 =item B<Sort>
 169
 170 This implements a multi-level sort of a Tree::Simple heirarchy.
 171
 172 =item B<VariableDepthClone>
 173
 174 A Visitor for cloning parts of Tree::Simple hierarchy
 175
 176 =back
 177
 178 =head1 BUGS
 179
 180 None that I am aware of. Of course, if you find a bug, let me know, and I will be sure to fix it.
 181
 182 =head1 CODE COVERAGE
 183
 184 I use B<Devel::Cover> to test the code coverage of my tests, below is the B<Devel::Cover> report on this module test suite.
 185
 186  -------------------------------------------- ------ ------ ------ ------ ------ ------ ------
 187  File                                           stmt branch   cond    sub    pod   time  total
 188  -------------------------------------------- ------ ------ ------ ------ ------ ------ ------
 189  Tree/Simple/VisitorFactory.pm                 100.0  100.0    n/a  100.0  100.0    0.4  100.0
 190  Tree/Simple/Visitor/BreadthFirstTraversal.pm  100.0  100.0   66.7  100.0  100.0    2.5   96.3
 191  Tree/Simple/Visitor/PostOrderTraversal.pm     100.0  100.0   77.8  100.0  100.0    1.7   96.3
 192  Tree/Simple/Visitor/PreOrderTraversal.pm      100.0    n/a   33.3  100.0  100.0    0.7   90.5
 193  Tree/Simple/Visitor/CreateDirectoryTree.pm    100.0   85.7   86.7  100.0  100.0    3.4   95.8
 194  Tree/Simple/Visitor/LoadClassHierarchy.pm     100.0   73.1   33.3  100.0  100.0    4.9   89.2
 195  Tree/Simple/Visitor/LoadDirectoryTree.pm      100.0   89.3   85.2  100.0  100.0   26.1   94.7
 196  Tree/Simple/Visitor/FindByNodeValue.pm        100.0  100.0   86.7  100.0  100.0    3.1   98.3
 197  Tree/Simple/Visitor/FindByPath.pm             100.0  100.0   66.7  100.0  100.0    1.2   97.9
 198  Tree/Simple/Visitor/FindByUID.pm              100.0  100.0   86.7  100.0  100.0    2.9   98.3
 199  Tree/Simple/Visitor/GetAllDescendents.pm      100.0  100.0   77.8  100.0  100.0    2.3   97.1
 200  Tree/Simple/Visitor/PathToRoot.pm             100.0   87.5   75.0  100.0  100.0    0.8   95.1
 201  Tree/Simple/Visitor/Sort.pm                   100.0  100.0   77.8  100.0  100.0    8.8   98.1
 202  Tree/Simple/Visitor/ToNestedArray.pm          100.0  100.0   66.7  100.0  100.0    1.5   96.5
 203  Tree/Simple/Visitor/ToNestedHash.pm           100.0  100.0   66.7  100.0  100.0    1.4   96.5
 204  Tree/Simple/Visitor/FromNestedArray.pm        100.0   94.4   81.8  100.0  100.0    8.1   96.6
 205  Tree/Simple/Visitor/FromNestedHash.pm         100.0   91.7   77.8  100.0  100.0    4.8   95.9
 206  Tree/Simple/Visitor/VariableDepthClone.pm     100.0  100.0   66.7  100.0  100.0   25.5   97.3
 207  -------------------------------------------- ------ ------ ------ ------ ------ ------ ------
 208  Total                                         100.0   93.8   76.3  100.0  100.0  100.0   96.1
 209  -------------------------------------------- ------ ------ ------ ------ ------ ------ ------
 210
 211 =head1 SEE ALSO
 212
 213 These Visitor classes are meant to work with L<Tree::Simple> hierarchies, you should refer to that module for more information.
 214
 215 =head1 AUTHOR
 216
 217 stevan little, E<lt>stevan@iinteractive.comE<gt>
 218
 219 =head1 COPYRIGHT AND LICENSE
 220
 221 Copyright 2004, 2005 by Infinity Interactive, Inc.
 222
 223 L<http://www.iinteractive.com>
 224
 225 This library is free software; you can redistribute it and/or modify
 226 it under the same terms as Perl itself.
 227
 228 =cut
 229