1
2package Tree::Simple::VisitorFactory;
3
4use strict;
5use warnings;
6
7our $VERSION = '0.10';
8
9sub new {
10    my ($class) = @_;
11    return bless \$class;
12}
13
14sub 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
251;
26
27__END__
28
29=head1 NAME
30
31Tree::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
46This 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
48I 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
56Returns 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
60Attempts 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
64This is an alias of C<get>.
65
66=back
67
68=head1 AVAILABLE VISITORS
69
70This 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
72This 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
80Given a Tree::Simple object, this Visitor will find the path back to the tree's root node.
81
82=item B<FindByPath>
83
84Given a path and Tree::Simple hierarchy, this Visitor will attempt to find the node specified by the path.
85
86=item B<FindByUID>
87
88Given a UID and Tree::Simple hierarchy, this Visitor will attempt to find the node with the same UID.
89
90=item B<FindByNodeValue>
91
92Given 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
102This implements a breadth-first traversal of a Tree::Simple hierarchy.
103
104=item B<PostOrderTraversal>
105
106Post-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
110Pre-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
120This visitor can be used to load a directory tree into a Tree::Simple hierarchy.
121
122=item B<CreateDirectoryTree>
123
124This 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
134Given a tree constructed from nested arrays, this Visitor will create the equivalent Tree::Simple heirarchy.
135
136=item B<ToNestedArray>
137
138Given a Tree::Simple heirarchy, this Visitor will create the equivalent tree constructed from nested arrays.
139
140=item B<FromNestedHash>
141
142Given a tree constructed from nested hashs, this Visitor will create the equivalent Tree::Simple heirarchy.
143
144=item B<ToNestedHash>
145
146Given 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
156Given 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
166Given a Tree::Simple instance this Visitor will return all the descendents recursively on down the hierarchy.
167
168=item B<Sort>
169
170This implements a multi-level sort of a Tree::Simple heirarchy.
171
172=item B<VariableDepthClone>
173
174A Visitor for cloning parts of Tree::Simple hierarchy
175
176=back
177
178=head1 BUGS
179
180None 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
184I 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
213These 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
217stevan little, E<lt>stevan@iinteractive.comE<gt>
218
219=head1 COPYRIGHT AND LICENSE
220
221Copyright 2004, 2005 by Infinity Interactive, Inc.
222
223L<http://www.iinteractive.com>
224
225This library is free software; you can redistribute it and/or modify
226it under the same terms as Perl itself.
227
228=cut
229
230