blib/lib/String/Tests.pm

filter: Statementstmt 96.3% 26 / 27 Branchbran 94.4% 17 / 18 Conditioncond 33.3% 1 / 3 MC/DCmcdc 0.0% 0 / 2 Subroutinesub 100% 4 / 4 Podpod 100% 1 / 1 totaltotal 89.0% 49 / 55 CC 12 SCAR 23.0
CC
12
Cov
92%
pass
12.2
BEGIN
1.0
BEGIN
1.0
CRAP 9.9
↑ Summary
1 package String::Tests;
2  
3 3 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 3 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 3 ▶use Carp 'croak';
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 =head1 NAME
8  
9 String::Tests - run a series of tests on a string
10  
11 =head1 VERSION
12  
13 Version 0.05
14  
15 =cut
16  
17 3 our $VERSION = '0.05';
18  
19  
20 =head1 SYNOPSIS
21  
22 use String::Tests;
23 my $boolean = String::Tests->pass( $string, \@tests );
24  
25 =head1 DESCRIPTION
26  
27 It is very common (for example when doing user input validation) to have to run
28 a series of tests on a single string of data. This module attempts to ease the
29 burden of doing so, by amalgamating all tests into a single boolean method call.
30  
31 =head2 EXPORT
32  
33 None by default
34  
35 =head1 METHODS
36  
37 =head2 pass
38  
39 =cut
40  
41 24 ▶sub pass {
Subroutine pass: called CC=12 SCAR=25.0
Pod documented
42 24 ▶ shift if $_[0] eq __PACKAGE__ or ref $_[0];
Branch: 1 branch
BranchTrueFalseTotal
if $_[0] eq __PACKAGE__ or ref $_[0] 24 0 24
Condition33%1/3
$_[0] eq __PACKAGE__ or ref $_[0]
l!l&&r!l&&!r
2400
MC/DC0%0/2
$_[0] eq __PACKAGE__ or ref $_[0]
$_[0] eq __PACKAGE__ ref $_[0]
Truth table33%1/3
A or B
A= $_[0] eq __PACKAGE__B= ref $_[0]
ABresult
1X1
011
000
43 24 my ($string, $tests) = @_;
44 24 my $type = ref $tests;
45 24 ▶ if ($type eq 'ARRAY') {
Branch: 3 branches
BranchTrueFalseTotal
if ($type eq 'ARRAY') { } 17 7 24
elsif ($type eq 'Regexp') { } 3 4 7
elsif ($type eq 'CODE') { } 3 1 4
46 17 for my $test (@$tests) { # boolean return values only when in list context
47 47 my $test_type = ref $test;
48 47 ▶ if ($test_type eq 'Regexp') {
Branch: 2 branches
BranchTrueFalseTotal
if ($test_type eq 'Regexp') { } 36 11 47
elsif ($test_type eq 'CODE') { } 10 1 11
49 36 ▶ return if $string !~ $test; # simple boolean test
Branch: 1 branch
BranchTrueFalseTotal
unless $string =~ /$test/ 8 28 36
50 } elsif ($test_type eq 'CODE') {
51 10 ▶ return if not $test->($string); # callback
Branch: 1 branch
BranchTrueFalseTotal
unless &$test($string) 5 5 10
52 } else {
53 1 croak "ERROR: type of tests must be 'Regexp' or 'CODE'.\n";
54 }
55 }
56 3 return 1; # boolean all tests passed
57 } elsif ($type eq 'Regexp') {
58 3 ▶ return ( $string =~ /$tests/g ) if wantarray; # assumes capture syntax
Branch: 1 branch
BranchTrueFalseTotal
if wantarray 1 2 3
59 2 return $string =~ $tests; # simple boolean test
60 } elsif ($type eq 'CODE') {
61 3 return $tests->($string); # return whatever the code ref returned
62 }
63 1 croak "ERROR: type of tests must be 'ARRAY', 'Regexp' or 'CODE'.\n";
64 0 return;
65 }
66  
67 =head1 EXAMPLES
68  
69 The most useful case is of course to run a series of code and/or regexp tests on a
70 string. The example below shows a simple way to validate user password creation.
71  
72 my $boolean = String::Tests->pass( 'wimpy_password', [
73 qr/^[\w[:punct:]]{8,16}\z/, # character white list
74 qr/[A-Z]/, # force 1 upper case
75 qr/[a-z]/, # force 1 lower case
76 qr/\d/, # force 1 digit
77 qr/[[:punct:]]/, # force 1 punctuation symbol
78 sub {$self->SUPER::password_tests(@_)}}, # whatever else...
79 ]);
80  
81 When needed you can also run a single code ref or regexp. Whatever function you
82 implement will receive the string to be tested (in the example below,
83 'email@address.com') as $_[0].
84  
85 my $boolean = String::Tests->pass( 'email@address.com',
86 sub { use Email::Valid; return Email::Valid->rfc822(shift) }
87 );
88 my $boolean = String::Tests->pass( 'some_string', qr/some_regexp/ );
89  
90 While it's unlikely to be useful in most cases, you can also capture return values
91 from a regexp test into an array.
92  
93 my @blocks_abcd = String::Tests->pass( '10.0.0.1',
94 qr/^ (\d{1,3}) \. (\d{1,3}) \. (\d{1,3}) \. (\d{1,3}) \z/x
95 );
96  
97 When running a single code ref, pass() simply returns whatever your function does.
98  
99 my @domain_parts = String::Tests->pass( 'x.y.z.sub.domain.tld.stld',
100 sub {return split_domain_name(shift)}
101 );
102  
103 The pseduo-code below provides a simple example of form validation useful for
104 providing feedback to the user about errors. Use of constants can help optimize
105 complex sets of tests when operating in a persistant environment (such as
106 mod_perl).
107  
108 package MyPackage;
109  
110 use String::Tests;
111  
112 use constant PARAM_TESTS => {
113 username => [
114 q| must be 2-32 alpha-numeric, "." or "_" characters |,
115 [
116 qr/^[\w\.\-]{2,32}\z/,
117 qr/[a-z0-9]/i,
118 ],
119 ],
120 password => [
121 q| must have 8-16 dual case letters, numbers, and punctations |,
122 [
123 qr/^[\w[:punct:]]{8,16}\z/,
124 qr/[A-Z]/,
125 qr/[a-z]/,
126 qr/\d/,
127 qr/[[:punct:]]/,
128 ],
129 ],
130 email => [
131 q| must be a valid email address |,
132 sub { use Email::Valid; return Email::Valid->rfc822(shift) },
133 ],
134 };
135  
136 sub test_params { # ->test_params(qw( username password email ))
137 my ( $self, @param_fields ) = @_;
138 for my $field (@param_fields) {
139 my ( $error_message, $tests ) = @{ __PACKAGE__->PARAM_TESTS->{$field} };
140 # set error messages (if any) so you can alert the user
141 $self->errors->{$field} = $error_message
142 unless String::Tests->pass( $http_request->param($field), $tests );
143 }
144 }
145  
146 =head1 AUTHOR
147  
148 Shaun Fryer, C<< <pause.cpan.org at sourcery.ca> >>
149  
150 =head1 BUGS
151  
152 Please report any bugs or feature requests to C<bug-string-tests at rt.cpan.org>, or through
153 the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=String-Tests>. I will be notified, and then you'll
154 automatically be notified of progress on your bug as I make changes.
155  
156  
157  
158  
159 =head1 SUPPORT
160  
161 You can find documentation for this module with the perldoc command.
162  
163 perldoc String::Tests
164  
165  
166 You can also look for information at:
167  
168 =over 4
169  
170 =item * RT: CPAN's request tracker
171  
172 L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=String-Tests>
173  
174 =item * AnnoCPAN: Annotated CPAN documentation
175  
176 L<http://annocpan.org/dist/String-Tests>
177  
178 =item * CPAN Ratings
179  
180 L<http://cpanratings.perl.org/d/String-Tests>
181  
182 =item * Search CPAN
183  
184 L<http://search.cpan.org/dist/String-Tests>
185  
186 =back
187  
188  
189 =head1 ACKNOWLEDGEMENTS
190  
191 Everybody. :)
192 L<http://en.wikipedia.org/wiki/Standing_on_the_shoulders_of_giants>
193  
194 =head1 COPYRIGHT & LICENSE
195  
196 Copyright 2008 Shaun Fryer, all rights reserved.
197  
198 This program is free software; you can redistribute it and/or modify it
199 under the same terms as Perl itself.
200  
201  
202 =cut
203  
204 3 1; # End of String::Tests
↑ Summary