Random/WordList.pm

filter: Statementstmt 97.8% 46 / 47 Branchbran 75.0% 15 / 20 Conditioncond 40.0% 4 / 10 MC/DCmcdc 0.0% 0 / 6 Subroutinesub 100% 7 / 7 Podpod 100% 3 / 3 totaltotal 80.6% 75 / 93 CC 15 SCAR 20.4
CC
15
Cov
84%
get_words
11.8
new
5.2
BEGIN
1.0
CRAP 7.7
« Random.pm ↑ Summary
1 ################################################################################
2 # Data::Random
3 #
4 # A module used to generate random data.
5 #
6 # Author: Adekunle Olonoh
7 # Date: October 2000
8 ################################################################################
9  
10 package Data::Random::WordList;
11  
12 ################################################################################
13 # - Modules and Libraries
14 ################################################################################
15 2 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
16 2 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
17  
18 2 ▶use FileHandle;
Subroutine BEGIN: called CC=1 SCAR=0.0
19 2 ▶use File::Basename qw(dirname);
Subroutine BEGIN: called CC=1 SCAR=0.0
20  
21 ################################################################################
22 # - Global Constants and Variables
23 ################################################################################
24 2 our $VERSION = '0.15';
25  
26 ################################################################################
27 # - Subroutines
28 ################################################################################
29  
30 ################################################################################
31 # new()
32 ################################################################################
33 130 ▶sub new {
Subroutine new: called CC=5 SCAR=16.6
Pod documented
34 130 my $proto = shift;
35 130 my %options = @_;
36  
37 # Check if what was passed in was a prototype reference or a class name
38 130 ▶ my $class = ref($proto) || $proto;
Condition33%1/3
ref $proto || $proto
l!l&&r!l&&!r
01300
MC/DC0%0/2
ref $proto || $proto
ref $proto $proto
Truth table33%1/3
A || B
A= ref $protoB= $proto
ABresult
1X1
011
000
39  
40 130 ▶ $options{'wordlist'} ||= dirname($INC{'Data/Random.pm'}).'/Random/dict';
Condition50%1/2
$options{"wordlist"} ||= dirname($INC{"Data/Random.pm"}) . '/Random/dict'
l!l
1300
MC/DC0%0/1
$options{"wordlist"} ||= dirname($INC{"Data/Random.pm"}) . '/Random/dict'
$options{"wordlist"}
Truth table50%1/2
A
A= $options{"wordlist"}
Aresult
11
00
41  
42 # Create a new filehandle object
43 130 ▶ my $fh = new FileHandle $options{'wordlist'}
Branch: 1 branch
BranchTrueFalseTotal
my $fh = "FileHandle"->new($options{"wordlist"}) or die qq[could not open $options{"wordlist"} : $!] 130 0 130
44 or die "could not open $options{'wordlist'} : $!";
45  
46 # Calculate the number of lines in the file
47 130 my $size = 0;
48 130 ▶ while (<$fh>) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined($_ = readline $fh)) 3380 130 3510
49 3380 $size++;
50 }
51  
52 # Create the object
53 130 my $self = bless {
54 'fh' => $fh,
55 'size' => $size,
56 }, $class;
57  
58 130 return $self;
59 }
60  
61 ################################################################################
62 # close()
63 ################################################################################
64 130 ▶sub close {
Subroutine close: called CC=1 SCAR=0.0
Pod documented
65 130 my $self = shift;
66  
67 # Close the filehandle
68 130 $self->{'fh'}->close;
69 }
70  
71 ################################################################################
72 # get_words()
73 ################################################################################
74 130 ▶sub get_words {
Subroutine get_words: called CC=11 SCAR=24.7
Pod documented
75 130 my $self = shift;
76 130 ▶ my $num = shift || 1;
Condition50%1/2
shift() || 1
l!l
1300
MC/DC0%0/1
shift() || 1
shift()
Truth table50%1/2
A
A= shift()
Aresult
11
00
77  
78 130 my $fh = $self->{'fh'};
79  
80 # Perform some error checking
81 130 ▶ die 'the size value must be a positive integer'
Branch: 1 branch
BranchTrueFalseTotal
if $num < 0 or $num != int $num 0 130 130
Condition33%1/3
$num < 0 or $num != int $num
l!l&&r!l&&!r
00130
MC/DC0%0/2
$num < 0 or $num != int $num
$num < 0 $num != int $num
Truth table33%1/3
A or B
A= $num < 0B= $num != int $num
ABresult
1X1
011
000
82 if $num < 0 || $num != int($num);
83 die
84 "$num words were requested but only $self->{'size'} words exist in the wordlist"
85 130 ▶ if $num > $self->{'size'};
Branch: 1 branch
BranchTrueFalseTotal
if $num > $self->{"size"} 0 130 130
86  
87 # Pick which lines we want
88 130 my %rand_lines = ();
89 130 ▶ for ( my $i = 0 ; $i < $num ; $i++ ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($i < $num) 1224 130 1354
90 1224 my $rand_line;
91  
92 do {
93 2667 $rand_line = int( rand( $self->{'size'} ) );
94 1224 ▶ } while ( exists( $rand_lines{$rand_line} ) );
Branch: 1 branch
BranchTrueFalseTotal
exists $rand_lines{$rand_line} and do { do { $rand_line = int rand $self->{"size"} } } 1443 1224 2667
95  
96 1224 $rand_lines{$rand_line} = 1;
97 }
98  
99 130 my $line = 0;
100 130 my @rand_words = ();
101  
102 # Seek to the beginning of the filehandle
103 130 ▶ $fh->seek( 0, 0 ) or die "could not seek to position 0 in wordlist: $!";
Branch: 1 branch
BranchTrueFalseTotal
$fh->seek(0, 0) or die "could not seek to position 0 in wordlist: $!" 130 0 130
104  
105 # Now get the lines
106 130 ▶ while (<$fh>) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined($_ = readline $fh)) 3380 130 3510
107 3380 chomp;
108 3380 ▶ push ( @rand_words, $_ ) if $rand_lines{$line};
Branch: 1 branch
BranchTrueFalseTotal
if $rand_lines{$line} 1224 2156 3380
109  
110 3380 $line++;
111 }
112  
113 # Return an array or an array reference, depending on the context in which the sub was called
114 130 ▶ if ( wantarray() ) {
Branch: 1 branch
BranchTrueFalseTotal
if (wantarray) { } 0 130 130
115 0 return @rand_words;
116 }
117 else {
118 130 return \@rand_words;
119 }
120 }
121  
122 2 1;
123  
124  
125  
126 =head1 NAME
127  
128 Data::Random::WordList - Perl module to get random words from a word list
129  
130  
131 =head1 SYNOPSIS
132  
133 use Data::Random::WordList;
134  
135 my $wl = new Data::Random::WordList( wordlist => '/usr/dict/words' );
136  
137 my @rand_words = $wl->get_words(10);
138  
139 $wl->close();
140  
141  
142 =head1 DESCRIPTION
143  
144 Data::Random::WordList is a module that manages a file containing a list of words.
145  
146 The module expects each line of the word list file to contain only one word. It could thus be easily used to select random lines from a file, but for coherency's sake, I'll keep referring to each line as a word.
147  
148 The module uses a persistent filehandle so that there isn't a lot of overhead every time you want to fetch a list of random words. However, it's much more efficient to grab multiple words at a time than it is to fetch one word at a time multiple times.
149  
150 The module also refrains from reading the whole file into memory, so it can be safer to use with larger files.
151  
152  
153 =head1 METHODS
154  
155 =head2 new()
156  
157 Returns a reference to a new Data::Random::WordList object. Use the "wordlist" param to initialize the object:
158  
159 =over 4
160  
161 =item *
162  
163 wordlist - the path to the wordlist file. If a path isn't supplied, the wordlist distributed with this module is used.
164  
165 =back
166  
167 =head2 get_words([NUM])
168  
169 NUM contains the number of words you want from the wordlist. NUM defaults to 1 if it's not specified. get_words() dies if NUM is greater than the number of words in the wordlist. This function returns an array or an array reference depending on the context in which it's called.
170  
171 =head2 close()
172  
173 Closes the filehandle associated with the word list. It's good practice to do this every time you're done with the word list.
174  
175  
176 =head1 VERSION
177  
178 0.12
179  
180  
181 =head1 AUTHOR
182  
183 Originally written by: Adekunle Olonoh
184  
185 Currently maintained by: Buddy Burden (barefoot@cpan.org), starting with version 0.06
186  
187  
188 =head1 COPYRIGHT
189  
190 Copyright (c) 2000-2011 Adekunle Olonoh.
191 Copyright (c) 2011-2015 Buddy Burden.
192 All rights reserved. This program is free software; you
193 can redistribute it and/or modify it under the same terms as Perl itself.
194  
195  
196 =head1 SEE ALSO
197  
198 L<Data::Random>
199  
200 =cut
« Random.pm ↑ Summary