1Tree::Simple::Visitor(3U)ser Contributed Perl DocumentatiTornee::Simple::Visitor(3)
2
6 Tree::Simple::Visitor - Visitor object for Tree::Simple objects
7
9 use Tree::Simple;
10 use Tree::Simple::Visitor;
11 # create a visitor instance
13 my $visitor = Tree::Simple::Visitor->new();
14 # create a tree to visit
16 my $tree = Tree::Simple->new(Tree::Simple->ROOT)
17 ->addChildren(
18 Tree::Simple->new("1.0"),
19 Tree::Simple->new("2.0")
20 ->addChild(
21 Tree::Simple->new("2.1.0")
22 ),
23 Tree::Simple->new("3.0")
24 );
25 # by default this will collect all the
27 # node values in depth-first order into
28 # our results
29 $tree->accept($visitor);
30 # get our results and print them
32 print join ", ", $visitor->getResults(); # prints "1.0, 2.0, 2.1.0, 3.0"
33 # for more complex node objects, you can specify
35 # a node filter which will be used to extract the
36 # information desired from each node
37 $visitor->setNodeFilter(sub {
38 my ($t) = @_;
39 return $t->getNodeValue()->description();
40 });
41 # NOTE: this object has changed, but it still remains
43 # backwards compatible to the older version, see the
44 # DESCRIPTION section below for more details
45
47 This object has been revised into what I think is more intelligent
48 approach to Visitor objects. This is now a more suitable base class for
49 building your own Visitors. It is also the base class for the visitors
50 found in the Tree::Simple::VisitorFactory distribution, which includes
51 a number of useful pre-built Visitors.
52 While I have changed a number of things about this module, I have kept
54 it backwards compatible to the old way of using it. So the original
55 example code still works:
56 my @accumulator;
58 my $visitor = Tree::Simple::Visitor->new(sub {
59 my ($tree) = @_;
60 push @accumlator, $tree->getNodeValue();
61 },
62 Tree::Simple::Visitor->RECURSIVE);
63 $tree->accept($visitor);
65 print join ", ", @accumulator; # prints "1.0, 2.0, 2.1.0, 3.0"
67 But is better expressed as this:
69 my $visitor = Tree::Simple::Visitor->new();
71 $tree->accept($visitor);
72 print join ", ", $visitor->getResults(); # prints "1.0, 2.0, 2.1.0, 3.0"
73 This object is still pretty much a wrapper around the Tree::Simple
75 "traverse" method, and can be thought of as a depth-first traversal
76 Visitor object.
77
79 new ($func, $depth)
80 The new style interface means that all arguments to the constructor
81 are now optional. As a means of defining the usage of the old and
82 new, when no arguments are sent to the constructor, it is assumed
83 that the new style interface is being used. In the new style, the
84 $depth is always assumed to be equivalent to "RECURSIVE" and the
85 $func argument can be set with "setNodeFilter" instead. This is the
86 recommended way of doing things now. If you have been using the old
87 way, it is still there, and I will maintain backwards compatability
88 for a few more version before removing it entirely. If you are
89 using this module (and I don't even know if anyone actually is) you
90 have been warned. Please contact me if this will be a problem.
91 The old style constructor documentation is retained her for
93 reference:
94 The first argument to the constructor is a code reference to a
96 function which expects a Tree::Simple object as its only argument.
97 The second argument is optional, it can be used to set the depth to
98 which the function is applied. If no depth is set, the function is
99 applied to the current Tree::Simple instance. If $depth is set to
100 "CHILDREN_ONLY", then the function will be applied to the current
101 Tree::Simple instance and all its immediate children. If $depth is
102 set to "RECURSIVE", then the function will be applied to the
103 current Tree::Simple instance and all its immediate children, and
104 all of their children recursively on down the tree. If no $depth is
105 passed to the constructor, then the function will only be applied
106 to the current Tree::Simple object and none of its children.
107 includeTrunk ($boolean)
109 Based upon the value of $boolean, this will tell the visitor to
110 collect the trunk of the tree as well. It is defaulted to false (0)
111 in the new style interface, but is defaulted to true (1) in the old
112 style interface.
113 getNodeFilter
115 This method returns the CODE reference set with "setNodeFilter"
116 argument.
117 clearNodeFilter
119 This method clears node filter field.
120 setNodeFilter ($filter_function)
122 This method accepts a CODE reference as its $filter_function
123 argument. This code reference is used to filter the tree nodes as
124 they are collected. This can be used to customize output, or to
125 gather specific information from a more complex tree node. The
126 filter function should accept a single argument, which is the
127 current Tree::Simple object.
128 getResults
130 This method returns the accumulated results of the application of
131 the node filter to the tree.
132 setResults
134 This method should not really be used outside of this class, as it
135 just would not make any sense to. It is included in this class and
136 in this documenation to facilitate subclassing of this class for
137 your own needs. If you desire to clear the results, then you can
138 simply call "setResults" with no argument.
139 visit ($tree)
141 The "visit" method accepts a Tree::Simple and applies the function
142 set in "new" or "setNodeFilter" appropriately. The results of this
143 application can be retrieved with "getResults"
144
146 These constants are part of the old-style interface, and therefore will
147 eventually be deprecated.
148 RECURSIVE
150 If passed this constant in the constructor, the function will be
151 applied recursively down the hierarchy of Tree::Simple objects.
152 CHILDREN_ONLY
154 If passed this constant in the constructor, the function will be
155 applied to the immediate children of the Tree::Simple object.
156
158 None that I am aware of. The code is pretty thoroughly tested (see CODE
159 COVERAGE section in Tree::Simple) and is based on an (non-publicly
160 released) module which I had used in production systems for about 2
161 years without incident. Of course, if you find a bug, let me know, and
162 I will be sure to fix it.
163
165 I have written a set of pre-built Visitor objects, available on CPAN as
166 Tree::Simple::VisitorFactory.
167
169 stevan little, <stevan@iinteractive.com>
170
172 Copyright 2004-2006 by Infinity Interactive, Inc.
173 <http://www.iinteractive.com>
175 This library is free software; you can redistribute it and/or modify it
177 under the same terms as Perl itself.
178perl v5.12.0 2007-11-11 Tree::Simple::Visitor(3)