File Coverage

blib/lib/Launcher/Cascade/ListOfStrings.pm
Criterion Covered Total %
statement 21 21 100.0
branch 2 2 100.0
condition 2 2 100.0
subroutine 7 7 100.0
pod 2 2 100.0
total 34 34 100.0


line stmt bran cond sub pod time code
1             package Launcher::Cascade::ListOfStrings;
2              
3             =head1 NAME
4              
5             Launcher::Cascade::ListOfStrings - a wrapper around an array to make it inherit from Launcher::Cascade::Printable
6              
7             =head1 SYNOPSIS
8              
9             use Launcher::Cascade::ListOfStrings;
10              
11             my $l = new Launcher::Cascade::ListOfStrings
12             -list => [ 'some', 'strings', 'to', 'start', 'with' ],
13             ;
14              
15             push @$l, 'and', 'then', 'some';
16              
17             print $l->as_string;
18             print "$l"; # same as above
19              
20             # alter the formatting
21             $l->separator(q{, });
22             $l->preparator(sub { qq{"$_"} });
23              
24             print "$l\n"; # prints quoted strings separated by comas
25              
26             =head1 DESCRIPTION
27              
28             =cut
29              
30 12     12   28143 use strict;
  12         28  
  12         404  
31 12     12   69 use warnings;
  12         26  
  12         343  
32              
33 12     12   78 use base qw( Launcher::Cascade Launcher::Cascade::Printable );
  12         23  
  12         7321  
34              
35             =head2 Attributes
36              
37             =over 4
38              
39             =item B
40              
41             A coderef used to prepare each element in list() before including it the
42             generated string. The coderef will be invoked with C<$_> locally aliased to the
43             current element. By default, preparator() is the identity function (i.e., it
44             returns C<$_> untouched).
45              
46             =item B
47              
48             The string to insert between each element in list() when generating a string
49             (sort of like Perl's C<$"> built-in variable. See L). Defaults to the
50             empty string.
51              
52             =item B
53              
54             =item B
55              
56             Strings to prepend and, respectively, append, to the string representation of
57             the list(). Both default to the empty string.
58              
59             =cut
60              
61             Launcher::Cascade::make_accessors_with_defaults
62             string_before => q{}, # empty string
63             string_after => q{}, # empty string
64             separator => q{}, # empty string
65             preparator => sub { $_ }, # identity
66             ;
67              
68             =item B
69              
70             The reference to the array containing the elements. This can also be accessed
71             by dereferencing the object as if it were an array reference (see SYNOPSIS).
72              
73             =cut
74              
75             sub list {
76              
77 51     51 1 108 my $self = shift;
78              
79 51   100     579 my $old = $self->{_list} ||= [];
80 51 100       164 $self->{_list} = $_[0] if @_;
81 51         263 return $old;
82             }
83              
84 12     12   78 use overload '@{}' => '_as_list';
  12         27  
  12         58  
85              
86             sub _as_list {
87              
88 18     18   480 my $self = shift;
89 18         69 $self->list();
90             }
91              
92             =back
93              
94             =head2 Methods
95              
96             =over 4
97              
98             =item B
99              
100             Returns a string representation of the object. Each element in list() is first
101             passed on to the coderef in preparator(), and the list of results from
102             preparator() is concatenated with the value of separator().
103              
104             This method is called when the object is "stringified", i.e., when it is
105             interpolated in a double-quoted string.
106              
107             =back
108              
109             =head1 EXAMPLES
110              
111             my $l = new Launcher::Cascade::ListOfStrings -list => [ qw( frodo pippin merry sam ) ];
112              
113             $l->separator(q{, });
114             $l->preparator(sub { ucfirst });
115              
116             print "$l\n"; # "Frodo, Pippin, Merry, Sam" and a newline
117              
118             =cut
119              
120             sub as_string {
121              
122 27     27 1 56 my $self = shift;
123              
124 27         88 return $self->string_before() . join($self->separator(), map $self->preparator()->(), @{$self->list()}) . $self->string_after();
  27         118  
125             }
126              
127             =head1 SEE ALSO
128              
129             L
130              
131             =head1 AUTHOR
132              
133             Cédric Bouvier C<< >>
134              
135             =head1 COPYRIGHT & LICENSE
136              
137             Copyright (C) 2006 Cédric Bouvier, All Rights Reserved.
138              
139             This program is free software; you can redistribute it and/or modify it under
140             the same terms as Perl itself.
141              
142             =cut
143              
144             1; # end of Launcher::Cascade::ListOfStrings