File Coverage

blib/lib/List/Conditional.pm
Criterion Covered Total %
statement 21 21 100.0
branch 4 4 100.0
condition n/a
subroutine 6 6 100.0
pod 1 1 100.0
total 32 32 100.0


line stmt bran cond sub pod time code
1             package List::Conditional;
2              
3 2     2   46127 use warnings;
  2         7  
  2         69  
4 2     2   11 use strict;
  2         4  
  2         90  
5              
6             require Exporter;
7 2     2   12 use base qw(Exporter);
  2         8  
  2         212  
8             our @EXPORT = qw(clist);
9              
10 2     2   18 use Carp qw(croak);
  2         3  
  2         133  
11 2     2   1818 use List::MoreUtils qw(natatime);
  2         4606  
  2         434  
12              
13              
14             =head1 NAME
15              
16             List::Conditional - Create lists based on a condition for each element
17              
18              
19             =head1 VERSION
20              
21             Version 0.02
22              
23             =cut
24              
25             our $VERSION = '0.02';
26              
27              
28             =head1 SYNOPSIS
29              
30             use List::Conditional;
31              
32             # academic example
33             my @list = clist(1 => 'a', 0 => 'b', 1 => 'c');
34             # same as @list = ('a', 'c');
35            
36             # a more practical example
37             my @things_to_pack = clist(
38             $destination->is_rainy() => 'umbrella',
39             $destination->is_warm() => 'shorts',
40             $myself->is_sick() => 'meds',
41             $flight->duration() > 2 => 'pillow',
42             int $myself->children() => 'toys',
43             ...
44             );
45            
46            
47             =head1 EXPORT
48              
49             B is automatically exported, as it is the only function in this module.
50              
51              
52             =head1 FUNCTIONS
53              
54             =head2 clist
55              
56             B an even number of elements, interpreted as pairs of C< value>>
57              
58             B the list of values, for which the associated condition evaluates to true.
59              
60             This function provides a nice functional and highly readable approach to conditional list building,
61             instead of using imperative control structures like C and C
62             or the ternary operator C.
63              
64             Beware that all conditions and values are passed to B in list context,
65             and therefore explicitly enforce scalar context for your conditions and values,
66             as seen in the L.
67              
68             If you want multiple values per condition, you can use L as follows:
69              
70             use List::Flatten;
71            
72             my @things_to_pack = flat clist(
73             $destination->is_rainy() => 'umbrella',
74             $destination->is_warm() => ['shorts', 'sandals'],
75             $myself->is_sick() => 'meds',
76             $flight->duration() > 2 => 'pillow',
77             int $myself->children() => ['toys', 'candy'],
78             ...
79             );
80              
81             If you need alternative values in case the conditions do not hold,
82             then the ternary operator is right for you, not this function.
83              
84             =cut
85              
86             sub clist {
87 2 100   2 1 2086 croak "odd number of elements passed to clist, requires (condition => value)-pairs!" if @_ % 2;
88 1         3 my @result = ();
89 1         23 my $it = natatime 2, @_;
90 1         17 while (my ($condition, $element) = $it->()) {
91 3 100       19 push @result, $element if $condition;
92             }
93 1         15 return @result;
94             }
95              
96              
97             =head1 AUTHOR
98              
99             Darko Obradovic, C<< >>
100              
101              
102             =head1 BUGS
103              
104             Please report any bugs or feature requests to C, or through
105             the web interface at L. I will be notified, and then you'll
106             automatically be notified of progress on your bug as I make changes.
107              
108              
109             =head1 SUPPORT
110              
111             You can find documentation for this module with the perldoc command.
112              
113             perldoc List::Conditional
114              
115              
116             You can also look for information at:
117              
118             =over 4
119              
120             =item * RT: CPAN's request tracker
121              
122             L
123              
124             =item * AnnoCPAN: Annotated CPAN documentation
125              
126             L
127              
128             =item * CPAN Ratings
129              
130             L
131              
132             =item * Search CPAN
133              
134             L
135              
136             =back
137              
138              
139             =head1 COPYRIGHT & LICENSE
140              
141             Copyright 2009 Darko Obradovic, all rights reserved.
142              
143             This program is free software; you can redistribute it and/or modify it
144             under the same terms as Perl itself.
145              
146             =cut
147              
148             1;