ListUtil.pm

filter: Statementstmt 92.6% 76 / 82 Branchbran 81.8% 18 / 22 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 92.3% 24 / 26 Podpod 100% 22 / 22 totaltotal 92.1% 140 / 152 CC 22 SCAR 12.9
CC
22
Cov
90%
anytrue
12.0
anyfalse
12.0
mode
5.0
CRAP 3.6
↑ Summary ListUtilVMethods.pm »
1 package Template::Plugin::ListUtil;
2  
3 2 ▶use List::Util;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 2 ▶use Template::Plugin::Procedural;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 2 ▶use vars qw(@ISA $VERSION);
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 2 $VERSION = "0.02";
8 2 @ISA = qw(Template::Plugin::Procedural);
9  
10 =head1 NAME
11  
12 Template::Plugin::ListUtil - List::Util functions for TT
13  
14 =head1 SYNOPSIS
15  
16 [% mylist = [ 1, 2, 3, 4, 4, 3, 2, 5, 2 ] %]
17  
18 [% USE ListUtil %]
19 The largest value in our array is [% ListUtil.largest(mylist) %]
20  
21 [% USE ListUtilVMethods %]
22 The largest value in our array is [% mylist.largest %]
23  
24 =head1 DESCRIPTION
25  
26 This module provides a selection of handy functions for dealing with
27 lists in the Template Toolkit. Most of the functions are adapted
28 from those provided by or documented in L<List::Util>, though note
29 these have been altered in name and function to work better with
30 the template toolkit.
31  
32 To access the functions like class methods, simply use the plugin
33 from within a Template Toolkit template:
34  
35 [% USE ListUtil %]
36  
37 And then call the method against the ListUtil object.
38  
39 [% max = ListUtil.largest(mylist) %]
40  
41 Alternatively you can load the functions as vmethods:
42  
43 [% USE ListUtilVMethods %]
44 [% max = mylist.largest %]
45  
46 Using the VMethods plugin as above will cause the vmethods to be in
47 effect for the current template and all templates called from that
48 template. To allow all templates called from any instance of the
49 Template module load the module from Perl with the 'install'
50 parameter.
51  
52 use Template::Plugin::ListUtilVMethods 'install';
53  
54 =head1 FUNCTIONS PROVIDED
55  
56 These are the functions that you can use once you've loaded the
57 plugin.
58  
59 =head2 Finding the largest/smallest
60  
61 =over
62  
63 =item largest
64  
65 Return the numerically largest value of the list.
66  
67 =cut
68  
69 2 ▶sub largest { List::Util::max(@{ $_[0] }) }
Subroutine largest: called CC=1 SCAR=0.0
Pod documented
70  
71 =item largeststr
72  
73 Return the largest value of the list, sorted by unicode value
74  
75 =cut
76  
77 2 ▶sub largeststr { List::Util::maxstr(@{ $_[0] }) }
Subroutine largeststr: called CC=1 SCAR=0.0
Pod documented
78  
79 =item smallest
80  
81 Return the numerically smallest value of the list
82  
83 =cut
84  
85 2 ▶sub smallest { List::Util::min(@{ $_[0] }) }
Subroutine smallest: called CC=1 SCAR=0.0
Pod documented
86  
87 =item smalleststr
88  
89 Return the smallest value of the list, sorted by unicode value
90  
91 =cut
92  
93 2 ▶sub smalleststr { List::Util::minstr(@{ $_[0] }) }
Subroutine smalleststr: called CC=1 SCAR=0.0
Pod documented
94  
95 =back
96  
97 =head2 Simple Statistics
98  
99 =over
100  
101 =item total
102  
103 The sum of adding up all the elements in the list
104  
105 =cut
106  
107 48 ▶sub total { List::Util::reduce { $a + $b } @{ $_[0] } }
Subroutine __ANON__: called CC=1 SCAR=0.0
Subroutine total: called CC=1 SCAR=0.0
Pod documented
108  
109 =item even
110  
111 Returns true if and only if this list contains an even number
112 of items, or the list is empty.
113  
114 =cut
115  
116 12 ▶sub even { int(@{ $_[0] } / 2) == (@{ $_[0] } / 2) }
Subroutine even: called CC=1 SCAR=0.0
Pod documented
117  
118 =item odd
119  
120 Returns true if and only if this list contains an odd number
121 of items.
122  
123 =cut
124  
125 8 ▶sub odd { int(@{ $_[0] } / 2) != (@{ $_[0] } / 2) }
Subroutine odd: called CC=1 SCAR=0.0
Pod documented
126  
127 =item mean
128  
129 The mathematical mean (numerical average) of the list
130  
131 =cut
132  
133 2 ▶sub mean { total($_[0]) / @{ $_[0] } }
Subroutine mean: called CC=1 SCAR=0.0
Pod documented
134  
135 =item mode
136  
137 Mode returns a list of the most frequently occurring elements
138 in a list. For example, for the list:
139  
140 ["buffy", "buffy", "willow", "willow", "buffy" ]
141  
142 The list
143  
144 ["buffy"]
145  
146 Would be returned because "Buffy" occurs more times in the list
147 than any other element. However, for some lists have more than
148 one element that could be consider the most frequent:
149  
150 [ 1, 2, 3, 3, 2, 2, 3, 4, 5, 5 ]
151  
152 In which case C<mode> returns them all:
153  
154 [ 2, 3 ]
155  
156 You can use the virtual method C<first> on the resulting list from
157 C<mode> to pick an arbitrary value, or the C<mean> function (see above)
158 to to take an average of the values.
159  
160 =cut
161  
162 sub mode
163 4 ▶{
Subroutine mode: called CC=5 SCAR=16.1
Pod documented
164 4 my %hash;
165 4 $hash{ $_ }++ foreach (@{ $_[0] });
166  
167 4 my $list = [];
168 4 my $value = (values %hash)[0];
169 4 foreach my $key (keys %hash)
170 {
171 20 ▶ if ($hash{ $key } eq $value)
Branch: 2 branches
BranchTrueFalseTotal
if ($hash{$key} eq $value) { } 6 14 20
elsif ($hash{$key} > $value) { } 4 10 14
172 6 { push @{$list}, $key }
173 elsif ($hash{ $key } > $value )
174 4 { $list = [ $key ]; $value = $hash{ $key }}
175 }
176  
177 4 return $list;
178 }
179  
180 =item median
181  
182 Returns a list containing either the middle element of the list (if
183 the list is odd in length) or the middle two elements of the list (if
184 the list is even in length.) To get a mathematical median you should
185 presort the list (probably with the C<nsort> virtual method) before
186 you pass it to C<median>. Like with C<mode> you can use the virtual
187 method C<first> on the resulting list from C<median> to pick an
188 arbitrary value, or the C<mean> function (see above) to to take an
189 average of the values.
190  
191 =cut
192  
193 sub median
194 4 ▶{
Subroutine median: called CC=2 SCAR=6.9
Pod documented
195 4 my $list = shift;
196 4 my $mid = int(@{ $list } / 2);
197  
198 4 ▶ ( even($list) ) ? [ $list->[ $mid - 1], $list->[ $mid ] ]
Branch: 1 branch
BranchTrueFalseTotal
even($list) ? : 2 2 4
199 : [ $list->[ $mid ] ]
200 }
201  
202 =back
203  
204 =head2 Randomisation Functions
205  
206 =over
207  
208 =item shuffle
209  
210 Return a new list made up from randomly shuffled elements of the
211 list passed.
212  
213 =cut
214  
215 2 ▶sub shuffle { [ List::Util::shuffle(@{ $_[0] }) ] }
Subroutine shuffle: called CC=1 SCAR=0.0
Pod documented
216  
217 =item random
218  
219 Return a random item from the passed list.
220  
221 =cut
222  
223 6 ▶sub random { (@{ $_[0] })[rand(@{ $_[0] })] }
Subroutine random: called CC=1 SCAR=0.0
Pod documented
224  
225 =back
226  
227 =head2 Truth Functions
228  
229 =over
230  
231 =item anytrue / anyfalse
232  
233 Is at least one item in the list true / false?
234  
235 =cut
236  
237 # this function copyright Graham Barr
238 0 ▶sub anytrue { $_ && return 1 for @{ $_[0] }; 0 }
Subroutine anytrue: not called CC=3 SCAR=24.8
Pod documented
Branch: 1 branch
BranchTrueFalseTotal
$_ and return 1 0 0 0
239  
240 0 ▶sub anyfalse { $_ || return 1 for @{ $_[0] }; 0 }
Subroutine anyfalse: not called CC=3 SCAR=24.8
Pod documented
Branch: 1 branch
BranchTrueFalseTotal
$_ or return 1 0 0 0
241  
242 =item alltrue / allfalse
243  
244 Are all items (i.e. every single item) in the list true / false?
245  
246 =cut
247  
248 # this function copyright Graham Barr
249 8 ▶sub alltrue { $_ || return 0 for @{ $_[0] } ; 1 }
Subroutine alltrue: called CC=3 SCAR=11.0
Pod documented
Branch: 1 branch
BranchTrueFalseTotal
$_ or return 0 10 6 16
250  
251 8 ▶sub allfalse { $_ && return 0 for @{ $_[0] } ; 1 }
Subroutine allfalse: called CC=3 SCAR=11.0
Pod documented
Branch: 1 branch
BranchTrueFalseTotal
$_ and return 0 6 10 16
252  
253 =item nonetrue / nonefalse
254  
255 Is no element in the list true / false?
256  
257 =cut
258  
259 # this function copyright Graham Barr
260 8 ▶sub nonetrue { $_ && return 0 for @{ $_[0] } ; 1 }
Subroutine nonetrue: called CC=3 SCAR=11.0
Pod documented
Branch: 1 branch
BranchTrueFalseTotal
$_ and return 0 6 10 16
261  
262 8 ▶sub nonefalse { $_ || return 0 for @{ $_[0] } ; 1 }
Subroutine nonefalse: called CC=3 SCAR=11.0
Pod documented
Branch: 1 branch
BranchTrueFalseTotal
$_ or return 0 10 6 16
263  
264 =item notalltrue / notallfalse
265  
266 Is at least one element in the list false?
267  
268 =cut
269  
270 # this function copyright Graham Barr
271 8 ▶sub notalltrue { $_ || return 1 for @{ $_[0] } ; 0 }
Subroutine notalltrue: called CC=3 SCAR=11.0
Pod documented
Branch: 1 branch
BranchTrueFalseTotal
$_ or return 1 10 6 16
272  
273 8 ▶sub notallfalse { $_ && return 1 for @{ $_[0] } ; 0 }
Subroutine notallfalse: called CC=3 SCAR=11.0
Pod documented
Branch: 1 branch
BranchTrueFalseTotal
$_ and return 1 6 10 16
274  
275 =item true
276  
277 How many items are true?
278  
279 =cut
280  
281 # this function copyright Graham Barr
282 8 ▶sub true { scalar grep { $_ } @{ $_[0] } }
Subroutine true: called CC=1 SCAR=0.0
Pod documented
283  
284 =item false
285  
286 How many items are false?
287  
288 =cut
289  
290 # this function copyright Graham Barr
291 8 ▶sub false { scalar grep { !$_ } @{ $_[0] } }
Subroutine false: called CC=1 SCAR=0.0
Pod documented
292  
293 =back
294  
295 =head1 AUTHOR
296  
297 Written by Mark Fowler E<lt>mark@twoshortplanks.comE<gt>
298  
299 Uses the List::Util module, by Graham Barr <gbarr@pobox.com>.
300  
301 Except as indicated in comments in the code, Copyright Mark Fowler
302 2003; All Rights Reserved. As indicated by comments in code some code
303 Copyright Graham Barr (1997-2001).
304  
305 This program is free software; you can redistribute it
306 and/or modify it under the same terms as Perl itself.
307  
308 =head1 BUGS
309  
310 None known.
311  
312 Bugs should be reported to me via the CPAN RT system.
313 L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Template-Plugin-ListUtil>.
314  
315 =head1 SEE ALSO
316  
317 L<List::Util> (for doing this in Perl)
318  
319 L<Template::Plugin::VMethods> (details on how the vmethods are installed)
320  
321 =cut
322  
323 2 1;
↑ Summary ListUtilVMethods.pm »