blib/lib/String/Unique.pm

filter: Statementstmt 75.1% 106 / 141 Branchbran 45.4% 20 / 44 Conditioncond 9.5% 2 / 21 MC/DCmcdc 0.0% 0 / 10 Subroutinesub 82.3% 14 / 17 Podpod 85.7% 6 / 7 totaltotal 61.6% 148 / 240 CC 32 SCAR 37.4
CC
32
Cov
62%
getIndexByString
156.0
new
9.4
getStringByIndex
5.1
CRAP 42.2
↑ Summary
1 package String::Unique;
2  
3 4 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 4 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 4 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 4 ▶use Data::Dumper;
Subroutine BEGIN: called CC=1 SCAR=0.0
7 4 ▶use Digest::MD5 qw(md5_base64);
Subroutine BEGIN: called CC=1 SCAR=0.0
8  
9 4 ▶use constant DEBUG => 0;
Subroutine BEGIN: called CC=1 SCAR=0.0
10  
11 =head1 NAME
12  
13 String::Unique - A source of deterministic pseudorandom strings [DPS]. Objects
14 of this class will generate a series of DPS of a set length for a set 2 char
15 'salt' [similar to UNIX crypt's salt] and resettable string that is
16 assumed to be a date string [although this is not enforced].
17  
18 Note that if the date string is changed, the object resets itself and begins
19 to generate a new series for the new date string.
20  
21  
22 =head1 VERSION
23  
24 Version 1.10
25  
26 =cut
27  
28 4 our $VERSION = '1.10';
29  
30 =head1 SYNOPSIS
31  
32 use String::Unique;
33  
34 my $dayrefs = String::Unique->new({characterCount => 11, salt => 'AT',});
35 my $string = $dayrefs->getStringByIndex(9999);
36 ...
37  
38 =cut
39  
40 { # OO closure block
41  
42 4 my %charCount_of;
43 my %salt_of;
44 4 my %dateStructure_of;
45  
46 =pod
47  
48 =head1 METHODS
49  
50 =head2 new
51  
52 Class constructor new
53  
54 Requires a hash ref containing a salt, string length and date
55  
56 =cut
57  
58 12 ▶ sub new {
Subroutine new: called CC=8 SCAR=22.4
Pod documented
59 12 my ( $class, $parms ) = @_;
60 12 if (DEBUG) {
61 print STDERR "String::Unique::new($class,)\n ";
62 print STDERR Dumper($parms), "\n\n";
63 }
64 croak('A 2 character salt is required for object of this class')
65 unless ( exists( $parms->{salt} )
66 12 ▶ && ( $parms->{salt} =~ m{ \A \w \w \z }xms ) );
Branch: 1 branch
BranchTrueFalseTotal
unless exists $parms->{"salt"} and $parms->{"salt"} =~ / \A \w \w \z /msx 0 12 12
Condition33%1/3
exists $parms->{"salt"} and $parms->{"salt"} =~ / \A \w \w \z /msx
!ll&&!rl&&r
0012
MC/DC0%0/2
exists $parms->{"salt"} and $parms->{"salt"} =~ / \A \w \w \z /msx
exists $parms->{"salt"} $parms->{"salt"} =~ / \A \w \w \z /msx
Truth table33%1/3
A and B
A= exists $parms->{"salt"}B= $parms->{"salt"} =~ / \A \w \w \z /msx
ABresult
0X0
100
111
67 croak('A starting date is required for object of this class')
68 12 ▶ unless ( exists( $parms->{date} ) );
Branch: 1 branch
BranchTrueFalseTotal
unless exists $parms->{"date"} 0 12 12
69 croak(
70 'characterCount is a required paramater for objects of this class')
71 unless ( exists( $parms->{characterCount} )
72 12 ▶ && $parms->{characterCount} );
Branch: 1 branch
BranchTrueFalseTotal
unless exists $parms->{"characterCount"} and $parms->{"characterCount"} 0 12 12
Condition33%1/3
exists $parms->{"characterCount"} and $parms->{"characterCount"}
!ll&&!rl&&r
0012
MC/DC0%0/2
exists $parms->{"characterCount"} and $parms->{"characterCount"}
exists $parms->{"characterCount"} $parms->{"characterCount"}
Truth table33%1/3
A and B
A= exists $parms->{"characterCount"}B= $parms->{"characterCount"}
ABresult
0X0
100
111
73 12 $parms->{characterCount} =~ s{ [^\d] }{}xmsg; # only the digits, please
74 croak('Parameter characterCount must be numeric')
75 12 ▶ unless ( $parms->{characterCount} );
Branch: 1 branch
BranchTrueFalseTotal
unless $parms->{"characterCount"} 0 12 12
76 croak( 'Cowardly refusing to create a generator '
77 . 'producing less than 6 charactor strings' )
78 12 ▶ if ( $parms->{characterCount} < 6 );
Branch: 1 branch
BranchTrueFalseTotal
if $parms->{"characterCount"} < 6 0 12 12
79 12 my $self = bless \do { my $fly_wieght }, $class;
80 12 my $ident = $self->ident();
81 12 $salt_of{$ident} = $parms->{salt};
82 12 $charCount_of{$ident} = $parms->{characterCount};
83  
84 12 $self->_initializeDay( $parms->{date} );
85 12 if (DEBUG && DEBUG > 2) {
86 print STDERR Dumper($self), "\n\n";
87 print STDERR Dumper( \%dateStructure_of ),;
88 }
89 12 return $self;
90 }
91  
92 =pod
93  
94 =head2 reset
95  
96 Reset the day structure for date.
97  
98 =cut
99  
100 0 ▶ sub reset {
Subroutine reset: not called CC=1 SCAR=6.9
Pod documented
101 0 my ( $self, $date ) = @_;
102 0 if (DEBUG) {
103 print STDERR "String::Unique::reset(\$self, $date, ";
104 print STDERR ")\n";
105 }
106
107 0 return $self->_initializeDay($date);
108 }
109  
110 =pod
111  
112 =head2 getStringByIndex
113  
114 Return the unique string in the [index] sequence for the given date or today is date
115 is not supplied. This seldom used class method is optimized for memory not speed.
116  
117  
118 =cut
119  
120 10 ▶ sub getStringByIndex {
Subroutine getStringByIndex: called CC=5 SCAR=16.3
Pod documented
121 10 my ( $self, $index, $date ) = @_;
122 10 if (DEBUG) {
123 print STDERR "String::Unique::getStringByIndex(\$self, $index, ";
124 print STDERR "$date" if defined $date;
125 print STDERR ")\n";
126 }
127 10 my $ident = $self->ident();
128  
129 10 ▶ if ( !exists $dateStructure_of{$ident}->{$date} ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (exists $dateStructure_of{$ident}{$date}) 10 0 10
130 10 $self->_initializeDay($date);
131 }
132 10 my $daystruct = $dateStructure_of{$ident}->{$date};
133 10 if (DEBUG && DEBUG > 2) {
134 print STDERR "DATE: $date\n";
135 print STDERR "\%dateStructure_of:", Dumper( \%dateStructure_of ),
136 "\n";
137 print STDERR "daystruct:", Dumper($daystruct), "\n\n";
138 }
139 10 ▶ while ( $daystruct->{INDEX} <= $index ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($daystruct->{"INDEX"} <= $index) 26585 10 26595
140 26585 $self->_newUniqueString($date);
141 }
142  
143 # This is a wastefull sequential search for the index value
144 10 eval {keys %{ $daystruct->{STRINGS} }} ; # RESET the iterator!
145 10 ▶ while ( my ( $key, $value ) = each %{ $daystruct->{STRINGS} } ) {
Branch: 1 branch
BranchTrueFalseTotal
if (() = each %{$$daystruct{"STRINGS"};}) 18231 0 18231
146 # print STDERR "\$key => $key, \$value => $value, \$index => $index\n";
147 18231 ▶ if ( $index == $value ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($index == $value) 10 18221 18231
148 10 return $key;
149 }
150 }
151 0 croak "INDEX failure ", Dumper $daystruct;
152 0 return;
153 }
154  
155 =pod
156  
157 =head2 getIndexByString
158  
159 Return [index] for the unique string in the sequence for the given dat. This seldom used class method is optimized for memory not speed.
160  
161  
162 =cut
163  
164 0 ▶ sub getIndexByString {
Subroutine getIndexByString: not called CC=12 SCAR=50.5
Pod documented
165 0 my ( $self, $parms) = @_;
166 0 if (DEBUG) {
167 print STDERR "String::Unique::getIndexByString(\$self,\n";
168 print STDERR Dumper($parms);
169 print STDERR "\n)\n";
170 }
171  
172 return unless(
173 exists $parms->{target} && $parms->{target}
174 && exists $parms->{max} && $parms->{max}
175 && exists $parms->{date} && $parms->{date}
176 0 ▶ );
Branch: 1 branch
BranchTrueFalseTotal
unless exists $parms->{"target"} and $parms->{"target"} and exists $parms->{"max"} and $parms->{"max"} and exists $parms->{"date"} and $parms->{"date"} 0 0 0
Condition0%0/15
exists $parms->{"target"} and $parms->{"target"} and exists $parms->{"max"} and $parms->{"max"} and exists $parms->{"date"} and $parms->{"date"}
!ll&&!rl&&r
000
exists $parms->{"target"} and $parms->{"target"} and exists $parms->{"max"} and $parms->{"max"} and exists $parms->{"date"}
!ll&&!rl&&r
000
exists $parms->{"target"} and $parms->{"target"} and exists $parms->{"max"} and $parms->{"max"}
!ll&&!rl&&r
000
exists $parms->{"target"} and $parms->{"target"} and exists $parms->{"max"}
!ll&&!rl&&r
000
exists $parms->{"target"} and $parms->{"target"}
!ll&&!rl&&r
000
MC/DC0%0/6
exists $parms->{"target"} and $parms->{"target"} and exists $parms->{"max"} and $parms->{"max"} and exists $parms->{"date"} and $parms->{"date"}
exists $parms->{"target"} $parms->{"target"} exists $parms->{"max"} $parms->{"max"} exists $parms->{"date"} $parms->{"date"}
Truth table0%0/7
A and B and C and D and E and F
A= exists $parms->{"target"}B= $parms->{"target"}C= exists $parms->{"max"}D= $parms->{"max"}E= exists $parms->{"date"}F= $parms->{"date"}
ABCDEFresult
0XXXXX0
10XXXX0
110XXX0
1110XX0
11110X0
1111100
1111111
177  
178 0 my $index;
179 0 my $target = $parms->{target};
180 0 my $maxIndex = $parms->{max};
181 0 my $date = $parms->{date};
182 0 my $ident = $self->ident();
183  
184 0 ▶ if ( !exists $dateStructure_of{$ident}->{$date} ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (exists $dateStructure_of{$ident}{$date}) 0 0 0
185 0 $self->_initializeDay($date);
186 }
187 0 my $daystruct = $dateStructure_of{$ident}->{$date};
188 0 if (DEBUG && DEBUG > 2) {
189 print STDERR "DATE: $date\n";
190 print STDERR "\%dateStructure_of:", Dumper( \%dateStructure_of ),
191 "\n";
192 print STDERR "daystruct:", Dumper($daystruct), "\n\n";
193 }
194 0 eval {keys %{$daystruct->{STRINGS}};}; #Reset the iterator
195 0 ▶ while (my($str,$ndx) = each %{$daystruct->{STRINGS}}) {
Branch: 1 branch
BranchTrueFalseTotal
if (() = each %{$$daystruct{"STRINGS"};}) 0 0 0
196 0 ▶ if($str eq $target) {
Branch: 1 branch
BranchTrueFalseTotal
if ($str eq $target) 0 0 0
197 0 return $ndx;
198 }
199 }
200 0 ▶ while ( $daystruct->{INDEX} < $maxIndex) {
Branch: 1 branch
BranchTrueFalseTotal
if ($daystruct->{"INDEX"} < $maxIndex) 0 0 0
201 0 ▶ if ($self->getNextString($date) eq $target) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->getNextString($date) eq $target) 0 0 0
202 0 return ($daystruct->{INDEX} -1);
203 };
204 }
205  
206 # This is a wastefull sequential search for the index value
207 0 if (DEBUG) {
208 carp "INDEX failure ", Dumper $daystruct;
209 }
210 0 return;
211 }
212  
213 =pod
214  
215 =head2 getNextString
216  
217 The primary method of this class. In scalar context returns the next entry in the
218 daily queue of pseudorandom strings, in list context returns the next entry and
219 the day of year as a 3 digit string ie '012' == January 13th.
220  
221 =cut
222  
223 19 ▶ sub getNextString {
Subroutine getNextString: called CC=3 SCAR=11.0
Pod documented
224 19 my ( $self, $date ) = @_;
225 19 if (DEBUG && DEBUG > 1) {
226 print STDERR "String::Unique::getNextString($self, $date)\n";
227 }
228 19 my $ident = $self->ident();
229 19 ▶ if ( !exists $dateStructure_of{$ident}->{$date} ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (exists $dateStructure_of{$ident}{$date}) 4 15 19
230 4 my @keys = keys %{ $dateStructure_of{$ident} };
231 4 for my $key (@keys) {
232 4 delete $dateStructure_of{$ident}->{$key};
233 }
234 4 $self->_initializeDay($date);
235 }
236 19 return $self->_newUniqueString($date);
237 }
238  
239 =pod
240  
241 =head2 _initializeDay
242  
243 Private class method; sets up the queue for date $datestring
244  
245 =cut
246  
247 26 ▶ sub _initializeDay {
Subroutine _initializeDay: called CC=2 SCAR=6.9
248 26 my ( $self, $datestring ) = @_;
249 26 if (DEBUG) {
250 print STDERR "String::Unique::_initializeDay(\$self,$datestring)\n";
251 }
252 26 my $ident = $self->ident();
253 26 for my $ds (keys %{$dateStructure_of{$ident}}) {
254 10 delete $dateStructure_of{$ident}->{$ds};
255 }
256  
257 # Every date format string supplied generates a date structure
258 # which is a hash ref.
259 # The fields of this hash are as follows:
260 # SEED => the actual date string supplied, as formatted.
261 # OFFSET => the number of times we have called md5_base64
262 # for this sequence
263 # INDEX => the number of the current string in the sequence
264 # STRINGS => a hash of the strings generated to the resepctive INDEX
265  
266 26 $dateStructure_of{$ident}->{$datestring} = {
267 SEED => $datestring,
268 OFFSET => 0,
269 INDEX => 0,
270 STRINGS => {},
271 };
272 }
273  
274 =pod
275  
276 =head2 _newUniqueString
277  
278 Private class method; returns the next unique string in date: $datstring-s Queue
279  
280 =cut
281  
282 26604 ▶ sub _newUniqueString {
Subroutine _newUniqueString: called CC=3 SCAR=11.2
283 26604 my ( $self, $datestring ) = @_;
284 26604 if (DEBUG && DEBUG > 1) {
285 print STDERR "String::Unique::_newUniqueString(\$self,$datestring)\n";
286 }
287 26604 my $ident = $self->ident();
288 croak "Request for string from non-initialized date"
289 26604 ▶ unless ( exists $dateStructure_of{$ident}->{$datestring} );
Branch: 1 branch
BranchTrueFalseTotal
unless exists $dateStructure_of{$ident}{$datestring} 0 26604 26604
290 26604 my $daystruct = $dateStructure_of{$ident}->{$datestring};
291 26604 my $canidate = $self->_randCharString($datestring);
292  
293 # This while loop is what makes entries in this series 'Unique'.
294 26604 ▶ while ( exists $daystruct->{STRINGS}->{$canidate} ) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $daystruct->{"STRINGS"}{$canidate}) 0 26604 26604
295 0 $canidate = $self->_randCharString($datestring);
296 }
297 26604 $daystruct->{STRINGS}->{$canidate} = $daystruct->{INDEX};
298 26604 $daystruct->{INDEX}++;
299 26604 return $canidate;
300 }
301  
302 =pod
303  
304 =head2 _randCharString
305  
306 Private class method; returns a candidate string
307  
308 =cut
309  
310 26604 ▶ sub _randCharString {
Subroutine _randCharString: called CC=3 SCAR=11.0
311 26604 my ( $self, $datestring ) = @_;
312 26604 if (DEBUG && DEBUG > 1) {
313 print STDERR "String::Unique::_randCharString(\$self,$datestring)\n";
314 }
315 26604 my $ident = $self->ident();
316 croak "Request for string from non-initialized date"
317 26604 ▶ unless ( exists $dateStructure_of{$ident}->{$datestring} );
Branch: 1 branch
BranchTrueFalseTotal
unless exists $dateStructure_of{$ident}{$datestring} 0 26604 26604
318 26604 my $daystruct = $dateStructure_of{$ident}->{$datestring};
319 26604 my $rv = q{}; # Empty string to start
320 26604 ▶ while ( length $rv < $charCount_of{$ident} ) {
Branch: 1 branch
BranchTrueFalseTotal
if (length $rv < $charCount_of{$ident}) 35332 26604 61936
321 $rv .=
322 md5_base64( $salt_of{$ident}
323 . sprintf( "%07d", $daystruct->{OFFSET}++ )
324 35332 . $daystruct->{SEED} );
325 35332 $rv =~ s{ [a-z+\/] }{}xmsg;
326 }
327 # print STDERR "\n\$charCount_of{\$ident} => $charCount_of{$ident}\n";
328 26604 $rv = substr( $rv, 0, $charCount_of{$ident} );
329 26604 if (DEBUG && DEBUG > 1) {
330 print STDERR " _randCharString returns $rv\n";
331 }
332 26604 return $rv;
333 }
334  
335 =pod
336  
337 =head2 ident
338 Class method ident returns a string that uniquely identifies the object supplied
339  
340 =cut
341  
342 53287 ▶ sub ident {
Subroutine ident: called CC=3 SCAR=11.6
Pod documented
343 53287 my ($self) = @_;
344 53287 if (DEBUG && DEBUG > 2) {
345 print STDERR "String::Unique::ident(\$self)\n";
346 print STDERR "$self\n";
347 }
348 53287 ▶ return unless defined $self;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $self 0 53287 53287
349 53287 my $ident = "$self";
350  
351 53287 ▶ if (
Branch: 1 branch
BranchTrueFalseTotal
if ($ident =~ s/ \A [\w\=\:]+ \( 0x ([0-9a-f]+) \) .* \z/$1/msx) 53287 0 53287
352 $ident =~ s{ \A [\w\=\:]+ \( 0x ([0-9a-f]+) \) .* \z}
353 {$1}xms
354 )
355 {
356 53287 return $ident;
357 }
358 0 return;
359 }
360  
361 0 ▶sub dump {
Subroutine dump: not called CC=1 SCAR=6.9
Pod undocumented
362 0 my ($self) = @_;
363 0 my $ident = $self->ident();
364 my $rv = {
365 charCount_of => $charCount_of{$ident},
366 salt_of => $salt_of{$ident},
367 0 dateStructure_of => $dateStructure_of{$ident},
368 };
369 0 return $rv;
370 }
371  
372  
373  
374 12 ▶ sub DESTROY {
Subroutine DESTROY: called CC=1 SCAR=0.0
375 12 my ($self) = @_;
376 12 my $ident = $self->ident();
377 12 delete $charCount_of{$ident};
378 12 delete $salt_of{$ident};
379 12 delete $dateStructure_of{$ident};
380 12 return 1;
381 }
382  
383  
384 }
385  
386 =head1 AUTHOR
387  
388 Christian Werner Sr, << <saltbreez@cpan.org> >>
389  
390 =head1 BUGS
391  
392 Please report any bugs or feature requests to C<bug-string-unique at rt.cpan.org>, or through
393 the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=String-Unique>. I will be notified, and then you'll
394 automatically be notified of progress on your bug as I make changes.
395  
396  
397 =head1 SUPPORT
398  
399 You can find documentation for this module with the perldoc command.
400  
401 perldoc String::Unique
402  
403  
404 You can also look for information at:
405  
406 =over 4
407  
408 =item * RT: CPAN's request tracker (report bugs here)
409  
410 L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=String-Unique>
411  
412 =item * AnnoCPAN: Annotated CPAN documentation
413  
414 L<http://annocpan.org/dist/String-Unique>
415  
416 =item * CPAN Ratings
417  
418 L<http://cpanratings.perl.org/d/String-Unique>
419  
420 =item * Search CPAN
421  
422 L<http://search.cpan.org/dist/String-Unique/>
423  
424 =back
425  
426 =head1 ACKNOWLEDGEMENTS
427  
428 This module was adopted from the module Unique by the same author,
429 developed for Wells Fargo, see license and copyright
430  
431 =head1 COPYRIGHT & LICENSE
432  
433 Copyright 2007,2008 Wells Fargo, all rights reserved.
434 Copyright 2011 Christian Werner Sr.
435  
436 This program is free software; you can redistribute it and/or modify it
437 under the same terms as Perl itself.
438  
439 =cut
440  
441 4 1; # End of String::Unique
↑ Summary