File Coverage

blib/lib/AI/MicroStructure/List.pm
Criterion Covered Total %
statement 61 77 79.2
branch 6 10 60.0
condition 6 11 54.5
subroutine 14 17 82.3
pod 4 4 100.0
total 91 119 76.4


line stmt bran cond sub pod time code
1             package AI::MicroStructure::List;
2 1     1   5 use strict;
  1         1  
  1         25  
3 1     1   4 use AI::MicroStructure (); # do not export metaname and friends
  1         2  
  1         17  
4 1     1   579 use AI::MicroStructure::RemoteList;
  1         3  
  1         33  
5 1     1   5 use List::Util qw( shuffle );
  1         2  
  1         81  
6 1     1   4 use Carp;
  1         2  
  1         128  
7              
8             our @ISA = qw( AI::MicroStructure::RemoteList );
9             our $VERSION = '0.20';
10              
11             sub init {
12 2     2 1 4 my ($self, $data) = @_;
13 2         5 my $class = caller(0);
14              
15 2   33     13 $data ||= AI::MicroStructure->load_data($class);
16 2 50       6 croak "The optional argument to init() must be a hash reference"
17             if ref $data ne 'HASH';
18              
19 1     1   5 no strict 'refs';
  1         2  
  1         25  
20 1     1   4 no warnings;
  1         2  
  1         293  
21 2         8 ${"$class\::Theme"} = ( split /::/, $class )[-1];
  2         11  
22 2         4 @{"$class\::List"} = do { my %seen;
  2         7  
  2         3  
23 2         6 grep !$seen{$_}++, split /\s+/, $data->{names} };
24 2         11 *{"$class\::import"} = sub {
25 0     0   0 my $callpkg = caller(0);
26 0         0 my $structure = ${"$class\::Theme"};
  0         0  
27 0         0 my $meta = $class->new();
28 0     0   0 *{"$callpkg\::meta$structure"} = sub { $meta->name(@_) };
  0         0  
  0         0  
29 2         9 };
30 2         13 ${"$class\::meta"} = $class->new();
  2         63  
31             }
32              
33             sub name {
34 6     6 1 2253 my ( $self, $count ) = @_;
35 6         13 my $class = ref $self;
36              
37 6 50       17 if( ! $class ) { # called as a class method!
38 0         0 $class = $self;
39 1     1   5 no strict 'refs';
  1         1  
  1         52  
40 0         0 $self = ${"$class\::meta"};
  0         0  
41             }
42              
43 6 100 100     25 if( defined $count && $count == 0 ) {
44 1     1   4 no strict 'refs';
  1         2  
  1         81  
45             return
46 3 50       9 wantarray ? shuffle @{"$class\::List"} : scalar @{"$class\::List"};
  3         65  
  0         0  
47             }
48              
49 3   100     12 $count ||= 1;
50 3         11 my $list = $self->{cache};
51             {
52 1     1   5 no strict 'refs';
  1         1  
  1         156  
  3         3  
53 3 50       4 if (@{"$class\::List"}) {
  3         15  
54 0         0 push @$list, shuffle @{"$class\::List"} while @$list < $count;
  0         0  
55             }
56             }
57 3         11 splice( @$list, 0, $count );
58             }
59              
60             sub new {
61 4     4 1 13 my $class = shift;
62              
63 4         13 bless { cache => [] }, $class;
64             }
65              
66             sub structure {
67 0   0 0 1   my $class = ref $_[0] || $_[0];
68 1     1   6 no strict 'refs';
  1         1  
  1         54  
69 0           return ${"$class\::Theme"};
  0            
70             }
71              
72             1;
73              
74             __END__
75              
76             =head1 NAME
77              
78             AI::MicroStructure::List - Base class for simple lists of names
79              
80             =head1 SYNOPSIS
81              
82             package AI::MicroStructure::beatles;
83             use AI::MicroStructure::List;
84             our @ISA = ( AI::MicroStructure::List );
85             __PACKAGE__->init();
86             1;
87              
88             =head1 NAME
89              
90             AI::MicroStructure::beatles - The fab four structure
91              
92             =head1 DESCRIPTION
93              
94             Ladies and gentlemen, I<The Beatles>. I<(hysteric cries)>
95              
96             =cut
97              
98             __DATA__
99             # names
100             john paul
101             george ringo
102              
103             =head1 DESCRIPTION
104              
105             C<AI::MicroStructure::List> is the base class for all structures that are
106             meant to return a random excerpt from a predefined list.
107              
108             =head1 METHOD
109              
110             AI::MicroStructure::List offers several methods, so that the subclasses
111             are easy to write (see full example in L<SYNOPSIS>):
112              
113             =over 4
114              
115             =item new()
116              
117             The constructor of a single instance. An instance will not repeat items
118             until the list is exhausted.
119              
120             =item init()
121              
122             init() must be called when the subclass is loaded, so as to read the
123             __DATA__ section and fully initialise it.
124              
125             =item name( $count )
126              
127             Return $count names (default: C<1>).
128              
129             Using C<0> will return the whole list in list context, and the size of the
130             list in scalar context.
131              
132             =item structure()
133              
134             Return the structure name.
135              
136             =back
137              
138             =head1 AUTHOR
139              
140             Philippe 'BooK' Bruhat, C<< <book@cpan.org> >>
141              
142             =head1 COPYRIGHT
143              
144             Copyright 2005-2012 Philippe 'BooK' Bruhat, All Rights Reserved.
145              
146             =head1 LICENSE
147              
148             This program is free software; you can redistribute it and/or modify it
149             under the same terms as Perl itself.
150              
151             =cut
152