Tree::Simple::Visitor::Sort(3pm)

1Tree::Simple::Visitor::USsoerrt(C3o)ntributed Perl DocumTernetea:t:iSoinmple::Visitor::Sort(3)
2
3
4

NAME

6       Tree::Simple::Visitor::Sort - A Visitor for sorting a Tree::Simple
7       object heirarchy
8

SYNOPSIS

10         use Tree::Simple::Visitor::Sort;
11
12         # create a visitor object
13         my $visitor = Tree::Simple::Visitor::Sort->new();
14
15         $tree->accept($visitor);
16         # the tree is now sorted ascii-betically
17
18         # set the sort function to
19         # use a numeric comparison
20         $visitor->setSortFunction($visitor->NUMERIC);
21
22         $tree->accept($visitor);
23         # the tree is now sorted numerically
24
25         # set a custom sort function
26         $visitor->setSortFunction(sub {
27               my ($left, $right) = @_;
28               lc($left->getNodeValue()->{name}) cmp lc($right->getNodeValue()->{name});
29         });
30
31         $tree->accept($visitor);
32         # the tree's node are now sorted appropriately
33

DESCRIPTION

35       This implements a recursive multi-level sort of a Tree::Simple heirar‐
36       chy. I think this deserves some more explaination, and the best way to
37       do that is visually.
38
39       Given the tree:
40
41           1
42               1.3
43               1.2
44                   1.2.2
45                   1.2.1
46               1.1
47           4
48               4.1
49           2
50               2.1
51           3
52               3.3
53               3.2
54               3.1
55
56       A normal sort would produce the following tree:
57
58           1
59               1.1
60               1.2
61                   1.2.1
62                   1.2.2
63               1.3
64           2
65               2.1
66           3
67               3.1
68               3.2
69               3.3
70           4
71               4.1
72
73       A sort using the built-in REVERSE sort function would produce the fol‐
74       lowing tree:
75
76           4
77               4.1
78           3
79               3.3
80               3.2
81               3.1
82           2
83               2.1
84           1
85               1.3
86               1.2
87                   1.2.2
88                   1.2.1
89               1.1
90
91       As you can see, no node is moved up or down from it's current depth,
92       but sorted with it's siblings. Flexible customized sorting is possible
93       within this framework, however, this cannot be used for tree-balancing
94       or anything as complex as that.
95

METHODS

97       new There are no arguments to the constructor the object will be in its
98           default state. You can use the "setNodeFilter" and "setSortFunc‐
99           tion" methods to customize its behavior.
100
101       includeTrunk ($boolean)
102           Based upon the value of $boolean, this will tell the visitor to
103           include the trunk of the tree in the sort as well.
104
105       setNodeFilter ($filter_function)
106           This method accepts a CODE reference as it's $filter_function argu‐
107           ment and throws an exception if it is not a code reference. This
108           code reference is used to filter the tree nodes as they are sorted.
109           This can be used to gather specific information from a more complex
110           tree node. The filter function should accept a single argument,
111           which is the current Tree::Simple object.
112
113       setSortFunction ($sort_function)
114           This method accepts a CODE reference as it's $sort_function argu‐
115           ment and throws an exception if it is not a code reference.  The
116           $sort_function is used by perl's builtin "sort" routine to sort
117           each level of the tree. The $sort_function is passed two Tree::Sim‐
118           ple objects, and must return 1 (greater than), 0 (equal to) or -1
119           (less than). The sort function will override and bypass any node
120           filters which have been applied (see "setNodeFilter" method above),
121           they cannot be used together.
122
123           Several pre-built sort functions are provided. All of these func‐
124           tions assume that calling "getNodeValue" on the Tree::Simple object
125           will return a suitable sortable value.
126
127           REVERSE
128               This is the reverse of the normal sort using "cmp".
129
130           NUMERIC
131               This uses the numeric comparison operator "<=>" to sort.
132
133           REVERSE_NUMERIC
134               The reverse of the above.
135
136           ALPHABETICAL
137               This lowercases the node value before using "cmp" to sort. This
138               results in a true alphabetical sorting.
139
140           REVERSE_ALPHABETICAL
141               The reverse of the above.
142
143           If you need to implement one of these sorting routines, but need
144           special handling of your Tree::Simple objects (such as would be
145           done with a node filter), I suggest you read the source code and
146           copy and modify your own sort routine. If it is requested enough I
147           will provide this feature in future versions, but for now I am not
148           sure there is a large need.
149
150       visit ($tree)
151           This is the method that is used by Tree::Simple's "accept" method.
152           It can also be used on its own, it requires the $tree argument to
153           be a Tree::Simple object (or derived from a Tree::Simple object),
154           and will throw and exception otherwise.
155
156           It should be noted that this is a destructive action, since the
157           sort happens in place and does not produce a copy of the tree.
158

BUGS

160       None that I am aware of. Of course, if you find a bug, let me know, and
161       I will be sure to fix it.
162

CODE COVERAGE

164       See the CODE COVERAGE section in Tree::Simple::VisitorFactory for more
165       inforamtion.
166

ACKNOWLEDGEMENTS

173       Thanks to Vitor Mori for the idea and much of the code for this Visi‐
174       tor.
175

AUTHORS

177       Vitor Mori, <vvvv767@hotmail.com>
178
179       stevan little, <stevan@iinteractive.com>
180

COPYRIGHT AND LICENSE

182       Copyright 2004, 2005 by Vitor Mori & Infinity Interactive, Inc.
183
184       <http://www.iinteractive.com>
185
186       This library is free software; you can redistribute it and/or modify it
187       under the same terms as Perl itself.
188
189
190
191perl v5.8.8                       2005-07-13    Tree::Simple::Visitor::Sort(3)