blib/lib/Test/LectroTest/Generator.pm

filter: Statementstmt 100% 194 / 194 Branchbran 100% 68 / 68 Conditioncond 100% 15 / 15 MC/DCmcdc 100% 10 / 10 Subroutinesub 100% 54 / 54 Podpod 86.9% 20 / 23 totaltotal 99.1% 361 / 364 CC 44 SCAR 12.3
CC
44
Cov
100%
List
11.0
Int
5.0
Float
5.0
CRAP 3.4
« blib/lib/Test/LectroTest/Compat.pm ↑ Summary blib/lib/Test/LectroTest.pm »
1 package Test::LectroTest::Generator;
2 {
3 27 $Test::LectroTest::Generator::VERSION = '0.5001';
4 }
5  
6 27 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
7 27 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
8  
9 27 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
10  
11 27 ▶BEGIN {
Subroutine BEGIN: called CC=1 SCAR=0.0
12 27 ▶ use Exporter ();
Subroutine BEGIN: called CC=1 SCAR=0.0
13 27 our ($VERSION, @ISA, @EXPORT, @EXPORT_OK, %EXPORT_TAGS);
14  
15 27 my @gens = qw( &Int &Bool &Char &String &List &Hash
16 &Float &Elements &Unit );
17 27 my @combs = qw( &Paste &OneOf &Frequency &Sized &Each
18 &Apply &Map
19 &Concat &Flatten &ConcatMap &FlattenMap );
20 27 my @specials = qw( &Gen) ;
21  
22 27 @ISA = qw(Exporter);
23 27 @EXPORT = ();
24 27 @EXPORT_OK = ( @gens, @combs, @specials);
25 27 %EXPORT_TAGS = ( common => [@gens]
26 , combinators => [@combs]
27 , all => [@gens, @combs, @specials] );
28 }
29  
30 27 our @EXPORT_OK;
31  
32 =head1 NAME
33  
34 Test::LectroTest::Generator - Random value generators and combinators
35  
36 =head1 VERSION
37  
38 version 0.5001
39  
40 =head1 SYNOPSIS
41  
42 use Test::LectroTest::Generator qw(:common :combinators);
43  
44 my $int_gen = Int;
45 my $pct_gen = Int( range=>[0,100] );
46 my $flt_gen = Float( range=>[0,1] );
47 my $bln_gen = Bool;
48 my $chr_gen = Char( charset=>"a-z" );
49 my $str_gen = String( charset=>"A-Z0-9", length=>[3,] );
50 my $ary_gen = List( Int(sized=>0) );
51 my $hsh_gen = Hash( $str_gen, $pct_gen );
52 my $uni_gen = Unit( "e" ); # always returns "e"
53 my $elm_gen = Elements("e1", "e2", "e3", "e4");
54  
55 for my $sizing_guidance (1..100) {
56 my $i = $int_gen->generate( $sizing_guidance );
57 print "$i ";
58 }
59 print "\n";
60  
61 # generates single digits
62 my $digit_gen = Elements( 0..9 ); # or Int(range=>[0,9],sized=>0)
63  
64 # generates SSNs like "910-77-2236"
65 my $ssn_gen = Paste( Paste( ($digit_gen) x 3 ),
66 Paste( ($digit_gen) x 2 ),
67 Paste( ($digit_gen) x 4 ),
68 glue => "-" );
69  
70 # print 10 SSNs
71 print( map {$ssn_gen->generate($_)."\n"} 1..10 );
72  
73 my $english_dist_vowel_gen =
74 Frequency( [8.167,Unit("a")], [12.702,Unit("e")],
75 [6.996,Unit("i")], [ 7.507,Unit("o")],
76 [2.758,Unit("u")] );
77 # Source: http://www.csm.astate.edu/~rossa/datasec/frequency.html
78  
79 =head1 DESCRIPTION
80  
81 This module provides random value generators for common data types and
82 provides an interface and tools for creating your own generators. It
83 also provides generator combinators that can be used to create
84 more-complex generators by combining simple ones.
85  
86  
87 A generator is an object having a method C<generate>, which takes a
88 single argument, I<size> and returns a new random value. The
89 generated value is always a scalar. Generators that produce data
90 structures return references to them.
91  
92 =head2 Sizing guidance
93  
94 The C<generate> method interprets its I<size> argument as guidance
95 about the complexity of the value it should create. Typically,
96 smaller I<size> values result in smaller generated numbers and shorter
97 generated strings and lists. Some generators, for which sizing
98 doesn't make sense, ignore sizing guidance altogether; those that do
99 use sizing guidance can be told to ignore it via the B<sized>
100 modifier.
101  
102 The purpose of sizing is to allow LectroTest to generate simple values
103 at first and then, as testing progresses, to slowly ramp up the
104 complexity. In this way, counterexamples for obvious problems
105 will be easier for you to understand.
106  
107 =cut
108  
109  
110  
111 #==============================================================================
112 # modifier defaults
113  
114  
115 27 our %defaults = (
116 Int => { range => [-32768 , 32767 ], sized => 1 },
117 Float => { range => [-32768.0, 32767.0], sized => 1 },
118 List => { length => undef },
119 Char => { charset => "\x00-\x7f", },
120 String => { },
121 Paste => { glue => "" },
122 );
123  
124 #==============================================================================
125 # methods
126  
127 3195 ▶sub new {
Subroutine new: called CC=1 SCAR=0.0
Pod undocumented
128 3195 my $class = shift;
129 3195 return bless { @_ }, $class;
130 }
131  
132 7383819 ▶sub generate {
Subroutine generate: called CC=1 SCAR=0.0
Pod undocumented
133 7383819 my ($self, $size) = @_;
134 7383819 return scalar $self->{generator}->($size);
135 }
136  
137 #==============================================================================
138 # helpers
139  
140 371 ▶sub _defargs {
Subroutine _defargs: called CC=2 SCAR=6.9
141 371 my $gen_name = shift;
142 371 ▶ shift while ref($_[0]); # skip template, if any
Branch: 1 branch
BranchTrueFalseTotal
ref $_[0] and do { shift() } 167 371 538
143 371 return { %{$defaults{$gen_name}}, @_ };
144 }
145  
146 135 ▶sub _template {
Subroutine _template: called CC=2 SCAR=6.9
147 135 my $tmpl = [];
148 135 ▶ push @$tmpl, shift while ref($_[0]);
Branch: 1 branch
BranchTrueFalseTotal
ref $_[0] and do { push @$tmpl, shift() } 174 135 309
149 135 return $tmpl;
150 }
151  
152  
153 #==============================================================================
154 # plain old functions
155  
156 3195 ▶sub Gen(&) {
Subroutine Gen: called CC=1 SCAR=0.0
Pod undocumented
157 3195 my ($genfn) = @_;
158 3195 return Test::LectroTest::Generator->new(generator=>$genfn);
159 }
160  
161 =pod
162  
163 =head2 Generators
164  
165 The following functions create fully-formed generators, ready to use.
166 These functions are exported into your code's namespace if you ask for
167 C<:generators> or C<:all> when you C<use> this module.
168  
169 Each generator has a C<generate> method that you can call to extract
170 a new, random value from the generator.
171  
172 =over 4
173  
174 =item Int
175  
176 my $gen = Int( range=>[0,9], sized=>0 );
177  
178 Creates a generator for integer values, by default in the range [-32768,32767],
179 inclusive, but this can be changed via the optional B<range> modifier.
180  
181 =over 4
182  
183 =item Int( range=>[I<low>, I<high>] )
184  
185 Causes the generated values to be constrained to the range [I<low>,
186 I<high>], inclusive. By default, the range is [-32768, 32767].
187  
188 B<Note:> If your range is empty (i.e., I<low> E<gt> I<high>),
189 LectroTest will complain.
190  
191 B<Note:> If zero is not within the range you provide, sizing makes no
192 sense because the intersection of your range and the sizing range can
193 be empty, and thus you must turn off sizing with C<sized=E<gt>0>.
194 If you forget, LectroTest will complain.
195  
196  
197 =item Int( sized=>I<bool> )
198  
199 If true (the default), constrains the absolute value of the generated
200 integers to the sizing guidance provided to the C<generate> method.
201 Otherwise, the generated values are constrained only by the range.
202  
203 =back
204  
205  
206  
207 =cut
208  
209 139 ▶sub Int(@) {
Subroutine Int: called CC=5 SCAR=16.1
Pod documented
210 139 my $args = _defargs("Int", @_);
211 139 my ($sized, $rlo, $rhi) = ($args->{sized}, map int, @{$args->{range}});
212 139 ▶ croak "range=>[$rlo,$rhi] is empty" if $rlo > $rhi;
Branch: 1 branch
BranchTrueFalseTotal
if $rlo > $rhi 2 137 139
213 137 ▶ if (!$sized) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($sized) 65 72 137
214 # if unsized, use this simpler generator
215 65 my $span = $rhi - $rlo + 1;
216 1693921 ▶ return Gen {
Subroutine __ANON__: called CC=1 SCAR=0.0
217 1693921 return $rlo + int(rand($span));
218 65 };
219 }
220 # otherwise, provide a sizing-capable generator
221 72 ▶ croak "the given range=>[$rlo,$rhi] does not contain zero "
Branch: 1 branch
BranchTrueFalseTotal
if 0 < $rlo or 0 > $rhi 2 70 72
Condition100%3/3
0 < $rlo or 0 > $rhi
l!l&&r!l&&!r
1170
MC/DC100%2/2
0 < $rlo or 0 > $rhi
0 < $rlo 0 > $rhi
Truth table100%3/3
A or B
A= 0 < $rloB= 0 > $rhi
ABresult
1X1
011
000
222 . "and cannot be used with a sized generator"
223 if 0 < $rlo || 0 > $rhi;
224 173518 ▶ return Gen {
Subroutine __ANON__: called CC=4 SCAR=13.9
225 173518 my ($lo, $hi) = ($rlo, $rhi);
226 173518 my $size = shift;
227 173518 ▶ if (defined $size) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $size) 103518 70000 173518
228 103518 $size = int( $size + 0.5 );
229 103518 ▶ $lo = -$size if -$size > $lo;
Branch: 1 branch
BranchTrueFalseTotal
if -$size > $lo 32107 71411 103518
230 103518 ▶ $hi = $size if $size < $hi;
Branch: 1 branch
BranchTrueFalseTotal
if $size < $hi 62522 40996 103518
231 }
232 173518 return $lo + int(rand($hi - $lo + 1));
233 70 };
234 }
235  
236 =pod
237  
238 =item Float
239  
240 my $gen = Float( range=>[-2.0,2.0], sized=>1 );
241  
242 Creates a generator for floating-point values, by default in the range
243 [-32768.0,32768.0), but this can be changed via the optional B<range> modifier.
244 By default Float generators are sized.
245  
246 =over 4
247  
248 =item Float( range=>[I<low>, I<high>] )
249  
250 Causes the generated values to be constrained to the range [I<low>,
251 I<high>). By default, the range is [-32768.0,32768.0). (Note that
252 the I<high> value itself can never be generated, but values
253 infinitesimally close to it can.)
254  
255  
256 B<Note:> If your range is empty (i.e., I<low> E<gt> I<high>),
257 LectroTest will complain.
258  
259 B<Note:> If zero is not within the range you provide, sizing makes no
260 sense because the intersection of your range and the sizing range can
261 be empty, and thus you must turn off sizing with C<sized=E<gt>0>.
262 If you forget, LectroTest will complain.
263  
264 =item Float( sized=>I<bool> )
265  
266 If true (the default), constrains the absolute value of the generated
267 values to the sizing guidance provided to the C<generate> method.
268 Otherwise, the generated values are constrained only by the range.
269  
270 =back
271  
272 =cut
273  
274 45 ▶sub Float(@) {
Subroutine Float: called CC=5 SCAR=16.1
Pod documented
275 45 my $args = _defargs("Float", @_);
276 45 my ($sized, $rlo, $rhi) = ($args->{sized}, @{$args->{range}});
277 45 ▶ croak "range=>[$rlo,$rhi] is empty" if $rlo > $rhi;
Branch: 1 branch
BranchTrueFalseTotal
if $rlo > $rhi 2 43 45
278 43 ▶ if (!$sized) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($sized) 14 29 43
279 # if unsized, use this simpler generator
280 14 my $span = $rhi - $rlo;
281 140007 ▶ return Gen {
Subroutine __ANON__: called CC=1 SCAR=0.0
282 140007 return $rlo + rand($span);
283 14 };
284 }
285 # otherwise, provide a sizing-capable generator
286 29 ▶ croak "the given range [$rlo,$rhi] does not contain zero "
Branch: 1 branch
BranchTrueFalseTotal
if $rlo > 0 or 0 > $rhi 2 27 29
Condition100%3/3
$rlo > 0 or 0 > $rhi
l!l&&r!l&&!r
1127
MC/DC100%2/2
$rlo > 0 or 0 > $rhi
$rlo > 0 0 > $rhi
Truth table100%3/3
A or B
A= $rlo > 0B= 0 > $rhi
ABresult
1X1
011
000
287 . "and cannot be used with a sized generator"
288 if $rlo > 0 || 0 > $rhi;
289 173963 ▶ return Gen {
Subroutine __ANON__: called CC=4 SCAR=13.9
290 173963 my ($lo, $hi) = ($rlo, $rhi);
291 173963 my $size = shift;
292 173963 ▶ if (defined $size) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $size) 103963 70000 173963
293 103963 ▶ $lo = -$size if -$size > $lo;
Branch: 1 branch
BranchTrueFalseTotal
if -$size > $lo 31953 72010 103963
294 103963 ▶ $hi = $size if $size < $hi;
Branch: 1 branch
BranchTrueFalseTotal
if $size < $hi 61953 42010 103963
295 }
296 173963 return $lo + rand($hi - $lo);
297 27 };
298 }
299  
300 =pod
301  
302 =item Bool
303  
304 my $gen = Bool;
305  
306 Creates a generator for boolean values: 0 for false, 1 for true.
307 The generator ignores sizing guidance.
308  
309 =cut
310  
311 5 ▶sub Bool(@) {
Subroutine Bool: called CC=1 SCAR=0.0
Pod documented
312 5 return Int( @_, range=>[0,1], sized=>0 );
313 }
314  
315 =pod
316  
317 =item Char
318  
319 my $gen = Char( charset=>"A-Za-z0-9_" );
320  
321 Creates a generator for characters. By default the characters are in
322 the ASCII range [0,127], inclusive, but this behavior can be changed
323 with the B<charset> modifier:
324  
325 =over 4
326  
327 =item Char( charset=>I<cset> )
328  
329 Characters will be drawn from the character set given by the
330 character-set specification I<cset>. The syntax of I<cset> is
331 similar the Perl C<tr> built-in and is a string comprised of
332 characters and character ranges:
333  
334 =over 4
335  
336 =item I<c>
337  
338 Adds the character I<c> to the set.
339  
340 =item I<c>-I<d>
341  
342 Adds the characters in the range I<c> through I<d> (inclusive) to the
343 set. Note: If I<c> is lexicographically greater than I<d>, the range
344 is empty, and no characters will be added to the set.
345  
346 =back
347  
348 Examples:
349  
350 =over 4
351  
352 =item charset=>"abcdwxyz"
353  
354 The characters "a", "b", "c", "d", "w", "x", "y", and "z" are in the set.
355  
356 =item charset=>"a-dx-z"
357  
358 Shorter version of the previous example.
359  
360 =item charset=>"\x00-\x7f"
361  
362 The ASCII character set.
363  
364 =item charset=>"-_A-Za-z0-9"
365  
366 The character set contains "-", "_", upper- and lower-case
367 ASCII letters, and the digits 0-9. Notice that the dash must
368 occur first so that it is not misinterpreted as denoting
369 a range of characters.
370  
371 =back
372  
373 =back
374  
375 =cut
376  
377 42 ▶sub _to_range($) {
Subroutine _to_range: called CC=1 SCAR=0.0
378 42 my ($lo, $hi) = @{shift()}[0,1];
379 42 [ map {chr} ord$lo .. ord $hi ]
380 }
381  
382 34 ▶sub _parse_charset($) {
Subroutine _parse_charset: called CC=3 SCAR=11.0
383 34 local ($_) = @_;
384 34 my @ranges;
385 34 ▶ while (/(.)(?:-(.))?/sg) {
Branch: 1 branch
BranchTrueFalseTotal
if (/(.)(?:-(.))?/gs) 42 34 76
386 42 ▶ push @ranges, [$1, defined $2 ? $2 : $1];
Branch: 1 branch
BranchTrueFalseTotal
defined $2 ? : 27 15 42
387 }
388 34 [ sort keys %{{ map {($_,1)} map {@{_to_range($_)}} @ranges }} ]
389 }
390  
391 34 ▶sub Char(@) {
Subroutine Char: called CC=1 SCAR=0.0
Pod documented
392 34 my $cset = _defargs("Char", @_)->{charset};
393 34 return Elements( @{ _parse_charset($cset) } )
394 }
395  
396 =pod
397  
398 =item List(I<elemgen>)
399  
400 my $gen = List( Bool, length=>[1,10] );
401  
402 Creates a generator for lists (which are returned as array refs). The
403 elements of the lists are generated by the generator given as
404 I<elemgen>. The lengths of the generated lists are constrained by
405 sizing guidance at the time of generation. You can override the
406 default sizing behavior using the optional B<length> modifier:
407  
408 When the list generator calls the element generator, it divides the
409 sizing guidance by the length of the list. For example, if the list
410 being generated will have 7 elements, when the list generator calls
411 the element generator to generate each element, it will scale the
412 sizing guidance by 1/7. In this way the sizing guidance provides
413 a rough constraint on the total number of elements produced,
414 regardless of the depth of the list structure being generated.
415  
416 =over 4
417  
418 =item List( ..., length=>I<N> )
419  
420 Generated lists are exactly length I<N>.
421  
422 =item List( ..., length=>[I<M>,] )
423  
424 Generated lists are at least length I<M>. (Maximum length is
425 constrained by sizing factor.)
426  
427 =item List( ..., length=>[I<M>,I<N>] )
428  
429 Generated lists are of length between I<M> and I<N>, inclusive.
430 Sizing guidance is ignored.
431  
432 =back
433  
434 B<Advanced Note:> If more than one I<elemgen> is given, they will be
435 used in turn to create successive elements. In this case, the length
436 of the list will be multiplied by the number of generators given. For
437 example, providing two generators will create double-length lists.
438  
439 =cut
440  
441  
442 124 ▶sub List(@) {
Subroutine List: called CC=11 SCAR=24.0
Pod documented
443 124 my $template = _template(@_);
444 480074 ▶ my $builder = sub {
Subroutine __ANON__: called CC=4 SCAR=13.9
445 480074 my ($len, $size) = @_;
446 480074 ▶ my $subsize = defined $size ? $size / ($len+1) : 1;
Branch: 1 branch
BranchTrueFalseTotal
defined $size ? : 480072 2 480074
447 480074 my @list;
448 480074 foreach (1..$len) {
449 2703353 foreach my $generator (@$template) {
450 2704667 push @list, $generator->generate($subsize);
451 }
452 }
453 480074 return \@list;
454 124 };
455  
456 # return generator customized for length specification
457  
458 124 my $lenspec = _defargs("List", @_)->{length};
459  
460 # case 0: length=>undef
461 124 ▶ if ( ! defined $lenspec ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $lenspec) 6 118 124
462 6 $lenspec = [0,]; # convert into case 2
463 }
464 # case 1: length=>N
465 124 ▶ if ( ! ref($lenspec) ) {
Branch: 3 branches
BranchTrueFalseTotal
if (not ref $lenspec) { } 80 44 124
elsif (ref $lenspec eq 'ARRAY' and @$lenspec == 1) { } 31 13 44
elsif (ref $lenspec eq 'ARRAY' and @$lenspec == 2) { } 10 3 13
466 80 my $n = $lenspec;
467 80 ▶ croak "length=>$n can't be < 0" if $n < 0;
Branch: 1 branch
BranchTrueFalseTotal
if $n < 0 1 79 80
468 80065 ▶ return Gen {
Subroutine __ANON__: called CC=1 SCAR=0.0
469 80065 return $builder->($lenspec, @_);
470 }
471 79 }
472 # case 2: length=>[M,]
473 ▶ elsif ( ref($lenspec) eq 'ARRAY' && @$lenspec == 1 ) {
Condition100%3/3
ref $lenspec eq "ARRAY" and @$lenspec == 1
!ll&&!rl&&r
11231
MC/DC100%2/2
ref $lenspec eq "ARRAY" and @$lenspec == 1
ref $lenspec eq "ARRAY" @$lenspec == 1
Truth table100%3/3
A and B
A= ref $lenspec eq "ARRAY"B= @$lenspec == 1
ABresult
0X0
100
111
474 31 my ($m) = @$lenspec;
475 31 ▶ croak "length=>[$m,] can't be < 0" if $m < 0;
Branch: 1 branch
BranchTrueFalseTotal
if $m < 0 1 30 31
476 320001 ▶ return Gen {
Subroutine __ANON__: called CC=2 SCAR=6.9
477 320001 my ($size) = @_;
478 320001 ▶ return $builder->( $m >= $size
Branch: 1 branch
BranchTrueFalseTotal
$m >= $size ? : 94000 226001 320001
479 ? $m
480 : $m + int(rand($size - $m + 1)),
481 @_);
482 30 };
483 }
484 # case 3: length=>[M,N]
485 ▶ elsif ( ref($lenspec) eq 'ARRAY' && @$lenspec == 2 ) {
Condition100%3/3
ref $lenspec eq "ARRAY" and @$lenspec == 2
!ll&&!rl&&r
1210
MC/DC100%2/2
ref $lenspec eq "ARRAY" and @$lenspec == 2
ref $lenspec eq "ARRAY" @$lenspec == 2
Truth table100%3/3
A and B
A= ref $lenspec eq "ARRAY"B= @$lenspec == 2
ABresult
0X0
100
111
486 10 my ($m,$n) = @$lenspec;
487 10 ▶ croak "length=>[$m,$n]) is invalid" if $m > $n || $m < 0;
Branch: 1 branch
BranchTrueFalseTotal
if $m > $n or $m < 0 2 8 10
Condition100%3/3
$m > $n or $m < 0
l!l&&r!l&&!r
118
MC/DC100%2/2
$m > $n or $m < 0
$m > $n $m < 0
Truth table100%3/3
A or B
A= $m > $nB= $m < 0
ABresult
1X1
011
000
488 80008 ▶ return Gen {
Subroutine __ANON__: called CC=1 SCAR=0.0
489 80008 return $builder->( $m + int(rand($n - $m + 1)), @_ )
490 8 };
491 }
492 # case 4: bad length specification
493 else {
494 3 croak "length specification length=>$lenspec is bad";
495 }
496 }
497  
498 =pod
499  
500 =item Hash(I<keygen>, I<valgen>)
501  
502 my $gen = Hash( String( charset=>"A-Z", length=>3 ),
503 Float( range=>[0.0, 100.0] );
504  
505 Creates a generator for hashes (which are returned as hash refs). The
506 keys of the hash are generated by the generator given as I<keygen>,
507 and the values are generated by the generator I<valgen>.
508  
509 The Hash generator takes an optional B<length> modifier that
510 specifies the desired hash length (= number of keys):
511  
512 =over 4
513  
514 =item Hash( ..., length=>I<length-spec> )
515  
516 Specifies the desired length of the generated hashes, using the same
517 I<length-spec> syntax as for the List generator. Note that the
518 generated hashes may be smaller than expected because of key
519 collision.
520  
521 =back
522  
523 =cut
524  
525 4 ▶sub Hash(@) {
Subroutine Hash: called CC=2 SCAR=6.9
Pod documented
526 croak "Hash(keygen,valgen,...) requires two generators"
527 4 ▶ unless @{_template(@_)} == 2;
Branch: 1 branch
BranchTrueFalseTotal
unless @{_template(@_);} == 2 1 3 4
528 3 my $listgen = List(@_);
529 2 ▶ return Gen {
Subroutine __ANON__: called CC=1 SCAR=0.0
530 2 return { @{$listgen->generate(@_)} }
531 3 };
532 }
533  
534 =pod
535  
536 =item String
537  
538 my $gen = String( length=>[3,], charset=>"A-Z" );
539  
540 Creates a generator for strings. By default the strings will
541 be drawn from the ASCII character set (0 through 127) and
542 be of length constrained by the sizing factor. Both defaults
543 can be changed using modifiers:
544  
545 =over 4
546  
547 =item String( charset=>I<cset> )
548  
549 Characters will be drawn from the character set given by the
550 character-set specification I<cset>. The syntax of I<cset> is
551 similar the Perl C<tr> operator and is a string comprised of
552 characters and character ranges. See Char for a full
553 description.
554  
555 =item String( length=>I<length-spec> )
556  
557 Specifies the desired length of generated strings, using the same
558 I<length-spec> syntax as for the List generator.
559  
560 =back
561  
562 =cut
563  
564 22 ▶sub String(@) {
Subroutine String: called CC=3 SCAR=11.0
Pod documented
565 22 my $args = _defargs("String", @_);
566 22 my ($cset, $length) = @$args{qw(charset length)};
567 22 ▶ my $lcgen = List(Char(defined $cset ? (charset=>$cset) : ()),
Branch: 2 branches
BranchTrueFalseTotal
defined $cset ? : 4 18 22
defined $length ? : 20 2 22
568 defined $length ? (length=>$length) : ());
569 240004 ▶ return Gen {
Subroutine __ANON__: called CC=1 SCAR=0.0
570 240004 join "", @{$lcgen->generate(@_)};
571 }
572 22 }
573  
574 =pod
575  
576 =item Elements(I<e1>, I<e2>, ...)
577  
578 my $gen = Elements( "alpha", "beta", "gamma" );
579  
580 Creates a generator that chooses among the given elements I<e1>, I<e2>,
581 ... with equal probability. Each call to the C<generate> method will
582 return one of the element values. Sizing guidance has no effect on
583 this generator.
584  
585 B<Note:> This generator builder does not accept modifiers. If you
586 pass any, they will be interpreted as elements to be added to the pool
587 from which the generator randomly selects, which is probably not
588 what you want.
589  
590 =cut
591  
592 38 ▶sub Elements(@) {
Subroutine Elements: called CC=2 SCAR=6.9
Pod documented
593 38 ▶ croak "Elements(e...) must be given at least one element" unless @_;
Branch: 1 branch
BranchTrueFalseTotal
unless @_ 1 37 38
594 37 return OneOf( map {Unit($_)} @_ );
595 }
596  
597 =pod
598  
599 =item Unit(I<e>)
600  
601 my $gen = Unit( "alpha" );
602  
603 Creates a generator that always returns the value I<e>. Not too
604 useful on its own but can be handy as a building block for combinators
605 to chew on. Naturally, sizing guidance has no effect on this
606 generator.
607  
608 B<Note:> This generator builder does not accept modifiers.
609  
610 =cut
611  
612 2748 ▶sub Unit($) {
Subroutine Unit: called CC=1 SCAR=0.0
Pod documented
613 2748 my ($e) = @_;
614 2846926 ▶ return Gen {
Subroutine __ANON__: called CC=1 SCAR=0.0
615 2846926 return $e;
616 }
617 2748 }
618  
619  
620 =pod
621  
622 =back
623  
624  
625  
626  
627  
628  
629 =head2 Generator combinators
630  
631 The following combinators allow you to build more complicated
632 generators from simpler ones. These combinators are exported into
633 your code's namespace if you ask for C<:combinators> or C<:all> when
634 you C<use> this module.
635  
636  
637 =over 4
638  
639 =item Paste(I<gens>..., glue=>I<str>)
640  
641 my $gen = Paste( (String(charset=>"0-9",length=>4)) x 4,
642 glue => " " );
643 # gens credit-card numbers like "4592 9459 9023 1369"
644  
645 my $lgen = Paste( List( String(charset=>"0-9",length=>4)
646 , length=>4 ), glue => " " );
647 # another way of doing the same
648  
649 Creates a combined generator that generates values by joining the
650 values generated by each of the supplied sub-generators I<gens>.
651 (Generated list values will have their elements "flattened" into the
652 rest of the generated results before joining.) The resulting string is
653 returned.
654  
655 The values are joined using the given glue string I<str>. If no
656 B<glue> modifier is provided, the default glue is the empty string.
657  
658 The sizing guidance given to the combined generator will
659 be passed unchanged to each of the sub-generators.
660  
661 =cut
662  
663 7 ▶sub Paste(@) {
Subroutine Paste: called CC=1 SCAR=0.0
Pod documented
664 7 my @gens = @{_template(@_)};
665 7 my $glue = _defargs("Paste", @_)->{glue};
666 7 ▶ Apply( sub { join $glue, map @$_, @_ }, Flatten(@gens) );
Subroutine __ANON__: called CC=1 SCAR=0.0
667 }
668  
669 =pod
670  
671 =item OneOf(I<gens>...)
672  
673 my $gen = OneOf( Unit(0), List(Int,length=>3) );
674 # generates scalar 0 or a 3-element list of integers
675  
676 Creates a combined generator that generates each value by selecting at
677 random (with equal probability) one of the sub-generators in I<gens>
678 and using that generator to generate the output value.
679  
680 The sizing guidance given to the combined generator will be passed
681 unchanged to the selected sub-generator.
682  
683 B<Note:> This combinator does not accept modifiers.
684  
685 =cut
686  
687  
688 38 ▶sub OneOf(@) {
Subroutine OneOf: called CC=1 SCAR=0.0
Pod documented
689 38 my $gens = \@_;
690 38 my $igen = Int(sized=>0,range=>[0, @_-1]);
691 1472914 ▶ return Gen {
Subroutine __ANON__: called CC=1 SCAR=0.0
692 1472914 return $gens->[$igen->generate]->generate(@_);
693 }
694 38 }
695  
696 =pod
697  
698 =item Frequency([I<freq1>, I<gen1>], [I<freq2>, I<gen2>], ...)
699  
700 my $gen = Frequency( [50, Unit("common" )],
701 [35, Unit("less common")],
702 [15, Unit("uncommon" )] );
703 # generates one of "common", "less common", or
704 # "uncommon" with respective probabilities
705 # 50%, 35%, and 15%.
706  
707 Creates a combined generator that generates each value by selecting at
708 random one of the generators I<gen1> or I<gen2> or ... and using that
709 generator to generate the output value. Each generator is selected
710 with probability proportional to its associated frequency. (If all of
711 the given frequencies are the same, the Frequency combinator
712 effectively becomes OneOf.) The frequencies can be any non-negative
713 numerical values you want and will be normalized to a 0-to-1 scale
714 internally. At least one frequency must be greater than zero.
715  
716 The sizing guidance given to the combined generator will be passed
717 unchanged to the selected sub-generator.
718  
719 B<Note:> This combinator does not accept modifiers.
720  
721 =cut
722  
723 8 ▶sub Frequency(@) {
Subroutine Frequency: called CC=5 SCAR=16.1
Pod documented
724 8 my @freqs = map {$_->[0]} @_;
725 8 my @gens = map {$_->[1]} @_;
726 8 ▶ if ((my @baddies = grep {$_ < 0} @freqs)) {
Branch: 1 branch
BranchTrueFalseTotal
if (my(@baddies) = grep({$_ < 0;} @freqs)) 1 7 8
727 1 croak "frequencies must be non-negative; got $baddies[0]";
728 }
729 7 my $total = 0;
730 7 $total += $_ foreach @freqs;
731 7 ▶ unless ($total) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($total) 2 5 7
732 2 croak "at least one frequency must be greater than zero";
733 }
734 5 @freqs = map {$_/$total} @freqs; # normalize to [0,1] scale
735 5 $total = 0;
736 5 $_ = $total += $_ for (@freqs); # turn into cumulative freqs
737 5 $freqs[-1] = 1; # just in case of round-off error
738 22000 ▶ return Gen {
Subroutine __ANON__: called CC=2 SCAR=6.9
739 22000 my $r = rand;
740 22000 my $i = 0;
741 22000 ▶ $i++ while $freqs[$i] < $r;
Branch: 1 branch
BranchTrueFalseTotal
$freqs[$i] < $r and do { ++$i } 90575 22000 112575
742 22000 return $gens[$i]->generate(@_);
743 }
744 5 }
745  
746 =pod
747  
748 =item Each(I<gens>...)
749  
750 my $gen = Each( Unit(1), Unit("X") );
751 # always generates [ 1, "X" ]
752  
753 Creates a generator that returns a list (array ref) whose
754 successive elements are the successive values generated
755 by the given generators I<gens>.
756  
757 The sizing guidance given to the combined generator will be passed
758 unchanged to each sub-generator.
759  
760 B<Note:> This combinator does not accept modifiers.
761  
762 (Note for technical buffs: C<Each(...)> is exactly equivalent to
763 C<List(..., length=E<gt>1)>).
764  
765 =cut
766  
767 55 ▶sub Each(@) {
Subroutine Each: called CC=1 SCAR=0.0
Pod documented
768 55 return List( @_, length=>1 );
769 }
770  
771  
772 =pod
773  
774 =item Apply(I<fn>, I<gens>...)
775  
776 my $gen = Apply( sub { $_[0] x $_[1] }
777 , Unit("X"), Unit(4) );
778 # always generates "XXXX"
779  
780 Creates a generator that applies the given function I<fn> to arguments
781 generated from each of the given sub-generators I<gens> and returns
782 the resulting value. Each sub-generator contributes one value, and
783 the values are passed to I<fn> as arguments in the same order as the
784 sub-generators were given to Apply.
785  
786 The sizing guidance given to the combined generator will be passed
787 unchanged to each sub-generator.
788  
789 B<Note:> The function I<fn> is always evaluated in scalar context.
790 If you need to generate an array, return it as an array reference.
791  
792 B<Note:> This combinator does not accept modifiers.
793  
794  
795 =cut
796  
797 33 ▶sub Apply(&@) {
Subroutine Apply: called CC=1 SCAR=0.0
Pod documented
798 33 my $f = shift;
799 33 my $g = Each( @_ );
800 29 ▶ return Gen {
Subroutine __ANON__: called CC=1 SCAR=0.0
801 29 scalar $f->( @{$g->generate(@_)} )
802 33 };
803 }
804  
805 =pod
806  
807 =item Map(I<fn>, I<gens>...)
808  
809 my $gen = Map( sub { "X" x $_[0] }
810 , Unit(4), Unit(3), Unit(0) );
811 # always generates [ "XXXX", "XXX", "" ]
812  
813 Creates a generator that applies the given function I<fn> to the
814 values generated by the given generators I<gen> one at a time and
815 returns a list (array ref) whose elements are each of the successive
816 results.
817  
818 The sizing guidance given to the combined generator will be passed
819 unchanged to each sub-generator.
820  
821 B<Note:> The function I<fn> is always evaluated in scalar context.
822 If you need to generate an array, return it as an array reference.
823  
824 B<Note:> This combinator does not accept modifiers.
825  
826 =cut
827  
828 18 ▶sub _Map {
Subroutine _Map: called CC=1 SCAR=0.0
829 18 my $f = shift;
830 18 my $g = Each( @_ );
831 15 ▶ return Gen {
Subroutine __ANON__: called CC=1 SCAR=0.0
832 15 [ map { scalar $f->($_) } @{ $g->generate(@_) } ]
833 18 };
834 }
835  
836 2 ▶sub Map(&@) {
Subroutine Map: called CC=1 SCAR=0.0
Pod documented
837 2 _Map(@_);
838 }
839  
840 =pod
841  
842 =item Concat(I<gens>...)
843  
844 my $gen = Concat( List( Unit(1), length=>3 )
845 , List( Unit("x"), length=>1 ) );
846 # always generates [1, 1, 1, "x"]
847  
848 Creates a generator that concatenates the values generated by each of
849 its sub-generators, resulting in a list (which is returned as a array
850 reference). The values returned by the sub-generators are expected to
851 be lists (array refs). If a sub-generator returns a scalar value, it
852 will be treated like a single-element list that contains the value.
853  
854 The sizing guidance given to the combined generator will be passed
855 unchanged to each sub-generator.
856  
857 B<Note:> If a sub-generator returns something other than a list or
858 scalar, you will get a run-time error.
859  
860 B<Note:> This combinator does not accept modifiers.
861  
862 =cut
863  
864 # we'll use this helper in Flatten and ConcatMap (and Paste)
865  
866 76 ▶sub _concat(@) {
Subroutine _concat: called CC=2 SCAR=6.9
867 76 ▶ [ map { ref($_) ? @{$_} : ($_) } @_ ];
Branch: 1 branch
BranchTrueFalseTotal
ref $_ ? : 54 46 100
868 }
869  
870 9 ▶sub Concat(@) {
Subroutine Concat: called CC=1 SCAR=0.0
Pod documented
871 9 Apply( \&_concat, @_ );
872 }
873  
874  
875 =pod
876  
877 =item Flatten(I<gens>...)
878  
879 my $gen = Flatten( Unit( [[[[[[ 1 ]]]]]] ) );
880 # generates [1]
881  
882 Flatten is just like Concat except that it recursively flattens any
883 sublists generated by the generators I<gen> and then concatenates them
884 to generate a final a list of depth one, regardless of the depth
885 of any sublists.
886  
887 The sizing guidance given to the combined generator will be passed
888 unchanged to each sub-generator.
889  
890 B<Note:> If a sub-generator returns something other than a list or
891 scalar, you will get a run-time error.
892  
893 B<Note:> This combinator does not accept modifiers.
894  
895 =cut
896  
897 sub _flatten(@);
898 62 ▶sub _flatten(@) {
Subroutine _flatten: called CC=2 SCAR=6.9
899 62 ▶ _concat map { ref($_) ? _flatten(@$_) : ($_) } @_ ;
Branch: 1 branch
BranchTrueFalseTotal
ref $_ ? : 40 43 83
900 }
901  
902 16 ▶sub Flatten(@) {
Subroutine Flatten: called CC=1 SCAR=0.0
Pod documented
903 16 Apply( \&_flatten, @_ );
904 }
905  
906 =pod
907  
908 =item ConcatMap(I<fn>, I<gens>)
909  
910 sub take_odds { my $x = shift;
911 $x % 2 ? [$x] : [] }
912 my $gen = ConcatMap( \&take_odds
913 , Unit(1), Unit(2), Unit(3) );
914 # generates [1, 3]
915  
916 Creates a generator that applies the function I<fn> to each of the
917 values generated by the given generators I<gen> in turn, and then
918 concatenates the results.
919  
920 The sizing guidance given to the combined generator will be passed
921 unchanged to each sub-generator.
922  
923 B<Note:> The function I<fn> is always evaluated in scalar context.
924 If you need to generate an array, return it as an array reference.
925  
926 B<Note:> If a sub-generator returns something other than a list or
927 scalar, you will get a run-time error.
928  
929 B<Note:> This combinator does not accept modifiers.
930  
931 =cut
932  
933 7 ▶sub ConcatMap(&@) {
Subroutine ConcatMap: called CC=1 SCAR=0.0
Pod documented
934 7 my $g = _Map( @_ );
935 6 ▶ return Gen {
Subroutine __ANON__: called CC=1 SCAR=0.0
936 6 _concat @{ $g->generate( @_ ) };
937 7 };
938 }
939  
940  
941 =pod
942  
943 =item FlattenMap(I<fn>, I<gens>)
944  
945 my $gen = FlattenMap( sub { [ ($_[0]) x 3 ] }
946 , Unit([1]), Unit([[2]]) );
947 # generates [1, 1, 1, 2, 2, 2]
948  
949 Creates a generator that applies the function I<fn> to each of the
950 values generated by the given generators I<gen> in turn, and then
951 flattens and concatenates the results.
952  
953 The sizing guidance given to the combined generator will be passed
954 unchanged to each sub-generator.
955  
956 B<Note:> The function I<fn> is always evaluated in scalar context.
957 If you need to generate an array, return it as an array reference.
958  
959 B<Note:> If a sub-generator returns something other than a list or
960 scalar, you will get a run-time error.
961  
962 B<Note:> This combinator does not accept modifiers.
963  
964 =cut
965  
966 9 ▶sub FlattenMap(&@) {
Subroutine FlattenMap: called CC=1 SCAR=0.0
Pod documented
967 9 my $g = _Map( @_ );
968 8 ▶ return Gen {
Subroutine __ANON__: called CC=1 SCAR=0.0
969 8 _flatten @{ $g->generate( @_ ) };
970 9 };
971 }
972  
973  
974 =pod
975  
976 =item Sized(I<fn>, I<gen>)
977  
978 my $gen = Sized { 2 * $_[0] } List(Int);
979 # ^ magnify sizing guidance by factor of two
980 my $gen2 = Sized { 10 } Int;
981 # ^ use constant guidance of 10
982  
983 Creates a generator that adjusts sizing guidance by passing it through
984 the function I<fn>. Then it calls the generator I<gen> with the
985 adjusted guidance and returns the result.
986  
987 B<Note:> This combinator does not accept modifiers.
988  
989 =cut
990  
991 17 ▶sub Sized(&$) {
Subroutine Sized: called CC=1 SCAR=0.0
Pod documented
992 17 my ($sizer, $gen) = @_;
993 140400 ▶ return Gen {
Subroutine __ANON__: called CC=1 SCAR=0.0
994 140400 return $gen->generate($sizer->(@_));
995 17 };
996 }
997  
998 =pod
999  
1000 =back
1001  
1002 =head2 Rolling your own generators
1003  
1004 You can create your own generators by creating any object that
1005 has a C<generate> method. Your method should accept as its
1006 first argument sizing guidance I<size> and, if it makes sense,
1007 adjust the complexity of the values it generates accordingly.
1008  
1009 The easiest way to create a generator is by using the magic function
1010 C<Gen>. It promotes a block of code into a generator. For example,
1011 here's a home-brew generator for times in ctime(3) format that
1012 is built on top of an Int generator:
1013  
1014 use Test::LectroTest::Generator qw( :common Gen );
1015  
1016 my $time_gen = Int(range=>[0, 2_147_483_647], sized=>0);
1017 my $ctime_gen = Gen {
1018 scalar localtime $time_gen->generate( @_ );
1019 };
1020  
1021 print($ctime_gen->generate($_), "\n") for 1..5;
1022 # Fri Jun 2 18:13:21 1978
1023 # Thu Mar 28 00:55:51 1974
1024 # Wed Mar 26 06:41:09 2025
1025 # Sun Sep 11 15:39:44 2016
1026 # Fri Dec 26 00:39:31 1975
1027  
1028 Alternatively, we could build the generator using the Apply
1029 combinator:
1030  
1031 my $ctime_gen2 = Apply { localtime $_[0] } $time_gen;
1032  
1033  
1034 B<Note:> C<Gen> is not exported into your code's namespace by default.
1035 If you want to use it, you must import it by name or import C<:all>
1036 when you use this module.
1037  
1038 =cut
1039  
1040 27 1;
1041  
1042  
1043  
1044 =head1 EXAMPLES
1045  
1046 Here are some examples to consider.
1047  
1048  
1049 =head2 Simple examples
1050  
1051 use strict;
1052 use Test::LectroTest::Generator qw(:common);
1053  
1054 show("Ints (sized by default)", Int);
1055  
1056 show("Floats (sized by default)", Float);
1057  
1058 show("Percentages (unsized)",
1059 Int( range=>[0,100], sized=>0 ));
1060  
1061 show("Lists (sized by default) of Ints (unsized) in [0,10]",
1062 List( Int( sized=>0, range=>[0,10] ) ));
1063  
1064 show("Uppercase-alpha identifiers at least 3 chars long",
1065 String( length=>[3,], charset=>"A-Z" ));
1066  
1067  
1068 show("Hashes (sized by default) of form AAA=>Digit",
1069 Hash( String( length=>3, charset=>"A-Z" ),
1070 Int( sized=>0, range=>[0,9] ) ));
1071  
1072 sub show {
1073 print "\n", shift(), "\n";
1074 my ($gen) = @_;
1075 for (1..10) {
1076 my $val = $gen->generate($_);
1077 printf "Size %2d: ", $_;
1078 if (ref $val eq "HASH") {
1079 my @pairs = map {"$_=>$val->{$_}"} keys %$val;
1080 print "{ @pairs }";
1081 }
1082 elsif (ref $val eq "ARRAY") {
1083 print "[ @$val ]"
1084 }
1085 else {
1086 print $val;
1087 }
1088 print "\n";
1089 }
1090 }
1091  
1092 =head2 Advanced examples
1093  
1094 For these examples we use C<Data::Dumper> to inspect the data
1095 structures we generate. Also, we import not only the common generator
1096 constructors (like Int) but also the generic Gen constructor, which
1097 lets us build generators out of blocks on the fly.
1098  
1099 use Data::Dumper;
1100 use Test::LectroTest::Generator qw(:common Gen);
1101  
1102 First, here's a recipe for building a list of lists of integers:
1103  
1104 my $loloi_gen = List( List( Int(sized=>0) ) );
1105 print Dumper($loloi_gen->generate(10));
1106  
1107 You may want to run the example several times to get a feel
1108 for the distribution of the generated output.
1109  
1110 Now, a more complicated example. Here we build sized trees of
1111 random depth using a recursive set of generators.
1112  
1113 my $tree_gen = do {
1114 my $density = 0.5;
1115 my $leaf_gen = Int( sized=>0 );
1116 my $tree_helper = \1;
1117 my $branch_gen = List( Gen { $$tree_helper->generate(@_) } );
1118 $tree_helper = \Gen {
1119 my ($size) = @_;
1120 return rand($size) < $density
1121 ? $leaf_gen->generate($size)
1122 : $branch_gen->generate($size + 1);
1123 };
1124 $$tree_helper;
1125 };
1126  
1127 print Dumper($tree_gen->generate(30));
1128  
1129 We define a tree as either a leaf or a branch, and we randomly decide
1130 between the two at each node in the growing tree. Leaves are just
1131 integers and become more likely when the sizing guidance diminishes
1132 (which happens as we go deeper). The code uses C<$density> as a
1133 control knob for leaf density. (Try re-running the above code after
1134 changing the value of C<$density>. Try 0, 1, and 2.) Branches,
1135 on the other hand, are lists of trees. Because branches generate
1136 trees, and trees generate branches, we use a reference trick
1137 to set up the mutually recursive relationship. This we encapsulate
1138 within a B<do> block for tidiness.
1139  
1140  
1141 =head1 SEE ALSO
1142  
1143 L<Test::LectroTest> gives a quick overview of automatic,
1144 specification-based testing with LectroTest.
1145  
1146  
1147 =head1 AUTHOR
1148  
1149 Tom Moertel (tom@moertel.com)
1150  
1151 =head1 INSPIRATION
1152  
1153 The LectroTest project was inspired by Haskell's
1154 QuickCheck module by Koen Claessen and John Hughes:
1155 http://www.cs.chalmers.se/~rjmh/QuickCheck/.
1156  
1157 =head1 COPYRIGHT and LICENSE
1158  
1159 Copyright (c) 2004-13 by Thomas G Moertel. All rights reserved.
1160  
1161 This program is free software; you can redistribute it and/or
1162 modify it under the same terms as Perl itself.
1163  
1164 =cut
« blib/lib/Test/LectroTest/Compat.pm ↑ Summary blib/lib/Test/LectroTest.pm »