Perlish/Smatch.pm

filter: Statementstmt 98.7% 80 / 81 Branchbran 79.4% 27 / 34 Conditioncond 83.3% 30 / 36 MC/DCmcdc 61.9% 13 / 21 Subroutinesub 100% 18 / 18 Podpod 100% 6 / 6 totaltotal 88.7% 174 / 196 CC 32 SCAR 16.0
CC
32
Cov
91%
match
8.0
is_registered
7.8
register_package
6.2
CRAP 4.9
« Perlish.pm ↑ Summary Perlish/Smatch/Hash.pm »
1 package Switch::Perlish::Smatch;
2
3 11 $VERSION = '1.0.1';
4
5 11 require Exporter;
6 11 @EXPORT_OK = qw/ smatch value_cmp /;
7 11 @ISA = 'Exporter';
8
9 11 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
10 11 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
11
12 11 ▶use vars '%REGISTER';
Subroutine BEGIN: called CC=1 SCAR=0.0
13 11 ▶use warnings::register;
Subroutine BEGIN: called CC=1 SCAR=0.0
14
15 11 ▶use Carp 'croak';
Subroutine BEGIN: called CC=1 SCAR=0.0
16 11 ▶use Scalar::Util 'blessed';
Subroutine BEGIN: called CC=1 SCAR=0.0
17
18 ## XXX: Convert %REGISTRY to a class heirarchy?
19 ## XXX: Make tests more consistent?
20 ## XXX: Provide an easy way to default to existing comparators?
21
22 ## XXX: Should this be done 'smartly?'
23 11 require Switch::Perlish::Smatch::Value;
24 11 require Switch::Perlish::Smatch::Undef;
25 11 require Switch::Perlish::Smatch::Scalar;
26 11 require Switch::Perlish::Smatch::Array;
27 11 require Switch::Perlish::Smatch::Hash;
28 11 require Switch::Perlish::Smatch::Code;
29 11 require Switch::Perlish::Smatch::Object;
30 11 require Switch::Perlish::Smatch::Regexp;
31
32 ## Thanks to merlyn for this snippet.
33 195 ▶sub _is_num {
Subroutine _is_num: called CC=1 SCAR=0.0
34 11 ▶ no warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
35 195 return ($_[0] & ~ $_[0]) eq "0";
36 }
37
38 83 ▶sub value_cmp {
Subroutine value_cmp: called CC=5 SCAR=16.1
Pod documented
39 83 my($a,$b) = @_;
40 ## Try to compare 2 strings then 2 numbers then do a regexp guesstimate.
41 83 ▶ !_is_num($a) and !_is_num($b) and return $a eq $b;
Branch: 1 branch
BranchTrueFalseTotal
_is_num($a) or _is_num($b) or return $a eq $b 29 54 83
Condition100%3/3
_is_num($a) or _is_num($b)
l!l&&r!l&&!r
27254
MC/DC100%2/2
_is_num($a) or _is_num($b)
_is_num($a) _is_num($b)
Truth table100%3/3
A or B
A= _is_num($a)B= _is_num($b)
ABresult
1X1
011
000
42 29 ▶ _is_num($a) and _is_num($b) and return $a == $b;
Branch: 1 branch
BranchTrueFalseTotal
_is_num($a) and _is_num($b) and return $a == $b 25 4 29
Condition100%3/3
_is_num($a) and _is_num($b)
!ll&&!rl&&r
2225
MC/DC100%2/2
_is_num($a) and _is_num($b)
_is_num($a) _is_num($b)
Truth table100%3/3
A and B
A= _is_num($a)B= _is_num($b)
ABresult
0X0
100
111
43 11 ▶ no warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
44 4 return $a =~ /\A$b\z/;
45 }
46
47 183 ▶sub match {
Subroutine match: called CC=8 SCAR=20.8
Pod documented
48 183 ▶ my $self = @_ == 3 ? shift : __PACKAGE__;
Branch: 1 branch
BranchTrueFalseTotal
@_ == 3 ? : 148 35 183
49 183 my($t, $m) = @_;
50 183 my($t_type, $m_type) = map _get_type($_), $t, $m;
51
52 ## Default to OBJECT if we don't have a registered class comparator.
53 183 ▶ $t_type = 'OBJECT'
Branch: 1 branch
BranchTrueFalseTotal
if builtin::blessed($t) and not $self->is_registered($t_type) 15 168 183
Condition100%3/3
builtin::blessed($t) and not $self->is_registered($t_type)
!ll&&!rl&&r
1521615
MC/DC100%2/2
builtin::blessed($t) and not $self->is_registered($t_type)
builtin::blessed($t) not $self->is_registered($t_type)
Truth table100%3/3
A and not(B)
A= builtin::blessed($t)B= not $self->is_registered($t_type)
ABresult
0X0
100
111
54 if blessed($t) and !$self->is_registered($t_type);
55 183 ▶ $m_type = 'OBJECT'
Branch: 1 branch
BranchTrueFalseTotal
if builtin::blessed($m) and not $self->is_registered($t_type, $m_type) 16 167 183
Condition100%3/3
builtin::blessed($m) and not $self->is_registered($t_type, $m_type)
!ll&&!rl&&r
1541316
MC/DC100%2/2
builtin::blessed($m) and not $self->is_registered($t_type, $m_type)
builtin::blessed($m) not $self->is_registered($t_type, $m_type)
Truth table100%3/3
A and not(B)
A= builtin::blessed($m)B= not $self->is_registered($t_type, $m_type)
ABresult
0X0
100
111
56 if blessed($m) and !$self->is_registered($t_type, $m_type);
57 ## Treat REF the same as SCALAR, i.e KISS.
58 $_ eq 'REF' and $_ = 'SCALAR'
59 183 ▶ for $t_type, $m_type;
Branch: 1 branch
BranchTrueFalseTotal
$_ eq "REF" and $_ = "SCALAR" 12 354 366
60
61 183 return $self->dispatch( $t_type, $m_type, $t, $m );
62 }
63
64 ## for exporting
65 11 *smatch = \&match;
66
67 ## Make this public?
68 366 ▶sub _get_type {
Subroutine _get_type: called CC=4 SCAR=13.9
69 366 my $foo = shift;
70 ## XXX: Is this the best way to check?
71 ## Get the class name, or the reference type, or we're a value/undef.
72 366 ▶ return blessed($foo) || ref($foo) || ( defined($foo) ? 'VALUE' : 'UNDEF' );
Branch: 1 branch
BranchTrueFalseTotal
defined $foo ? : 159 19 178
Condition83%5/6
builtin::blessed($foo) || ref $foo || (defined $foo ? 'VALUE' : 'UNDEF')
l!l&&r!l&&!r
1881780
builtin::blessed($foo) or ref $foo
l!l&&r!l&&!r
60128178
MC/DC0%0/3
builtin::blessed($foo) || ref $foo || (defined $foo ? 'VALUE' : 'UNDEF')
builtin::blessed($foo) ref $foo (defined $foo ? 'VALUE' : 'UNDEF')
Truth table75%3/4
A or B || C
A= builtin::blessed($foo)B= ref $fooC= (defined $foo ? 'VALUE' : 'UNDEF')
ABCresult
1XX1
01X1
0011
0000
73 }
74
75 192 ▶sub dispatch {
Subroutine dispatch: called CC=3 SCAR=11.4
Pod documented
76 192 my($self, $t_type, $m_type) = @_;
77 192 ▶ croak "No comparator found for topic '$t_type' => match '$m_type'"
Branch: 1 branch
BranchTrueFalseTotal
unless $self->is_registered($t_type, $m_type) 0 192 192
78 unless $self->is_registered( $t_type, $m_type );
79 192 ▶ my($t,$m) = @_ == 5 ?
Branch: 1 branch
BranchTrueFalseTotal
@_ == 5 ? : 192 0 192
80 @_[3,4] : ( $Switch::Perlish::TOPIC, $Switch::Perlish::MATCH );
81
82 ## XXX: Subvert the stack with a goto?
83 192 $REGISTER{ $t_type }{ $m_type }->( $t, $m );
84 }
85
86 709 ▶sub register {
Subroutine register: called CC=5 SCAR=16.2
Pod documented
87 709 my($self, %comp) = @_;
88 709 my($t_type, $m_type, $compare) = @comp{qw/ topic match compare /};
89
90 709 ▶ warnings::warn("Overriding existing comparator for $t_type<=>$m_type")
Branch: 1 branch
BranchTrueFalseTotal
if $self->is_registered($t_type, $m_type) and warnings::enabled() 1 708 709
Condition66%2/3
$self->is_registered($t_type, $m_type) and warnings::enabled()
!ll&&!rl&&r
70801
MC/DC50%1/2
$self->is_registered($t_type, $m_type) and warnings::enabled()
$self->is_registered($t_type, $m_type) warnings::enabled()
Truth table66%2/3
A and B
A= $self->is_registered($t_type, $m_type)B= warnings::enabled()
ABresult
0X0
100
111
91 if $self->is_registered($t_type, $m_type) and warnings::enabled;
92
93 709 $REGISTER{ $t_type }{ $m_type } = $compare;
94 1 ▶ $REGISTER{ $m_type }{ $t_type } = sub { $compare->(reverse @_) }
Subroutine __ANON__: called CC=1 SCAR=0.0
95 709 ▶ if exists $comp{reversible} and $comp{reversible};
Branch: 1 branch
BranchTrueFalseTotal
if exists $comp{"reversible"} and $comp{"reversible"} 1 708 709
Condition66%2/3
exists $comp{"reversible"} and $comp{"reversible"}
!ll&&!rl&&r
07081
MC/DC50%1/2
exists $comp{"reversible"} and $comp{"reversible"}
exists $comp{"reversible"} $comp{"reversible"}
Truth table66%2/3
A and B
A= exists $comp{"reversible"}B= $comp{"reversible"}
ABresult
0X0
100
111
96 }
97
98 89 ▶sub register_package {
Subroutine register_package: called CC=6 SCAR=18.2
Pod documented
99 89 my($self, $pkg, $topic) = @_;
100 89 ▶ my $prefix = defined($_[3]) ? $_[3] : '_';
Branch: 1 branch
BranchTrueFalseTotal
defined $_[3] ? : 0 89 89
101 89 ▶ my $reverse = defined($_[4]) ? $_[4] : 0;
Branch: 1 branch
BranchTrueFalseTotal
defined $_[4] ? : 0 89 89
102
103 89 ▶ croak "An empty prefix was provided (registering all subs is not desirable)"
Branch: 1 branch
BranchTrueFalseTotal
if length $prefix == 0 0 89 89
104 if length($prefix) == 0;
105
106 ## Let perl do the look-up.
107 11 ▶ my $tbl = do { no strict; \%{"$pkg\::"} };
Subroutine BEGIN: called CC=1 SCAR=0.0
108
109 89 for( grep /^$prefix/, keys %$tbl ) {
110 705 my $sub;
111 next
112 705 ▶ unless $sub = *{$tbl->{$_}}{CODE};
Branch: 1 branch
BranchTrueFalseTotal
unless $sub = *{$tbl->{$_};}{"CODE"} 0 705 705
113
114 705 Switch::Perlish::Smatch->register(
115 topic => $topic,
116 match => substr($_, 1),
117 compare => $sub,
118 reversible => $reverse,
119 );
120 }
121 }
122
123 969 ▶sub is_registered {
Subroutine is_registered: called CC=7 SCAR=20.5
Pod documented
124 969 my($self, $t_type, $m_type) = @_;
125
126 969 ▶ return ( exists $REGISTER{ $t_type } and defined $REGISTER{ $t_type } )
Branch: 1 branch
BranchTrueFalseTotal
if @_ == 2 35 934 969
Condition66%2/3
exists $Switch::Perlish::Smatch::REGISTER{$t_type} && defined $Switch::Perlish::Smatch::REGISTER{$t_type}
!ll&&!rl&&r
15020
MC/DC50%1/2
exists $Switch::Perlish::Smatch::REGISTER{$t_type} && defined $Switch::Perlish::Smatch::REGISTER{$t_type}
exists $Switch::Perlish::Smatch::REGISTER{$t_type} defined $Switch::Perlish::Smatch::REGISTER{$t_type}
Truth table66%2/3
A && B
A= exists $Switch::Perlish::Smatch::REGISTER{$t_type}B= defined $Switch::Perlish::Smatch::REGISTER{$t_type}
ABresult
0X0
100
111
127 if @_ == 2;
128 return ( exists $REGISTER{ $t_type } and defined $REGISTER{ $t_type }
129 and exists $REGISTER{ $t_type }{ $m_type }
130 934 ▶ and defined $REGISTER{ $t_type }{ $m_type } )
Branch: 1 branch
BranchTrueFalseTotal
if @_ == 3 934 0 934
Condition77%7/9
exists $Switch::Perlish::Smatch::REGISTER{$t_type} && defined $Switch::Perlish::Smatch::REGISTER{$t_type} && exists $Switch::Perlish::Smatch::REGISTER{$t_type}{$m_type} && defined $Switch::Perlish::Smatch::REGISTER{$t_type}{$m_type}
!ll&&!rl&&r
7240210
exists $Switch::Perlish::Smatch::REGISTER{$t_type} and defined $Switch::Perlish::Smatch::REGISTER{$t_type} and exists $Switch::Perlish::Smatch::REGISTER{$t_type}{$m_type}
!ll&&!rl&&r
93631210
exists $Switch::Perlish::Smatch::REGISTER{$t_type} and defined $Switch::Perlish::Smatch::REGISTER{$t_type}
!ll&&!rl&&r
930841
MC/DC50%2/4
exists $Switch::Perlish::Smatch::REGISTER{$t_type} && defined $Switch::Perlish::Smatch::REGISTER{$t_type} && exists $Switch::Perlish::Smatch::REGISTER{$t_type}{$m_type} && defined $Switch::Perlish::Smatch::REGISTER{$t_type}{$m_type}
exists $Switch::Perlish::Smatch::REGISTER{$t_type} defined $Switch::Perlish::Smatch::REGISTER{$t_type} exists $Switch::Perlish::Smatch::REGISTER{$t_type}{$m_type} defined $Switch::Perlish::Smatch::REGISTER{$t_type}{$m_type}
Truth table60%3/5
A and B and C && D
A= exists $Switch::Perlish::Smatch::REGISTER{$t_type}B= defined $Switch::Perlish::Smatch::REGISTER{$t_type}C= exists $Switch::Perlish::Smatch::REGISTER{$t_type}{$m_type}D= defined $Switch::Perlish::Smatch::REGISTER{$t_type}{$m_type}
ABCDresult
0XXX0
10XX0
110X0
11100
11111
131 if @_ == 3;
132
133 0 croak sprintf "Incorrect number of arguments for is_registered(%s)",
134 join(', ', @_);
135 }
136
137 11 1;
138
139 =pod
140
141 =head1 NAME
142
143 Switch::Perlish::Smatch - the 'smart' behind the matching in S::P
144
145 =head1 VERSION
146
147 1.0.1 - Updated and cleaned up documentation.
148
149 =head1 SYNOPSIS
150
151 use Switch::Perlish::Smatch 'smatch';
152
153 print 'yep'
154 if smatch $foo => \@bar;
155
156 =head1 DESCRIPTION
157
158 Given two values compare them in an intelligent fashion (i.e I<smart match>)
159 regardless of type. This is done by discerning the types of the values and
160 delegating to the associated subroutine, or C<croak>ing if one isn't available.
161
162 =head2 Glossary
163
164 =over
165
166 =item comparators
167
168 When talking about the subroutine that compares the two values in the document
169 below it will referred to as a I<comparator>
170
171 =item comparator category
172
173 A comparator category holds all the comparators for a given type.
174
175 =item comparator notation
176
177 Some handy notation for referring to specific I<comparators> is
178 C<< FOOE<lt>=>BAR >>, where C<FOO> is the topic and C<BAR> is the match (i.e the
179 first and second arguments, respectively).
180
181 =back
182
183 =head1 METHODS
184
185 =over
186
187 =item match( $topic, $match )
188
189 Try to smart match the C<$topic> against C<$match> by delegating to the
190 appopriate comparator. It returns the result of the match per the comparator,
191 but it can always be assumed that a successful match will evaluate to I<true>
192 and an unsuccessful one I<false>. This can also be exported as C<smatch>.
193
194 =item register( %hash )
195
196 The expected C<%hash> looks like this:
197
198 topic => $t_type,
199 match => $m_type,
200 compare => $sub,
201
202 So C<$sub> will be the registered comparator when the topic type is C<$t_type>
203 and the matching value is of type C<$m_type> e.g
204
205 my $foo = 'a string';
206 my $bar = [qw/ an array /];
207 smatch $foo, $bar;
208
209 In this case the C<$t_type> is C<VALUE> and the C<$m_type> is C<ARRAY>. If
210 one were to override the default comparator for C<< VALUEE<lt>=>ARRAY >>
211 using C<register()> then it would be done like this:
212
213 Switch::Perlish::Smatch->register(
214 topic => 'VALUE',
215 match => 'ARRAY',
216 compare => sub {
217 my($t, $m) = @_;
218 return grep /$t/, @$m;
219 },
220 );
221
222 If you run the code above you should get a warning noting that there is an
223 existing comparator for that type combination. To suppress this and any other
224 warnings from this module just add C<no warnings 'Switch::Perlish::Smatch'>.
225
226 This method is aimed at adding comparators for objects so they can be used
227 seamlessly in C<switch> calls. So instead of defaulting to the existing
228 C<OBJECT> comparators a user-defined comparator would be used, with more
229 desirable results. For more information see L</"Creating a new comparator">
230 below.
231
232 If your comparator is reversible, i.e the arguments can be reversed and the
233 result will be the same, then you can pass in the C<reversible> argument e.g
234
235
236 Switch::Perlish::Smatch->register(
237 topic => 'My::Obj',
238 match => 'ARRAY',
239 compare => sub {
240 my($t, $m) = @_;
241 return $t->cmp( $m );
242 },
243 reversible => 1,
244 );
245
246 So both the C<< My::Obj<=>VALUE >> and C<< VALUEE<lt>=>My::Obj >> comparators
247 will be setup, where C<< VALUEE<lt>=>My::Obj >> will behave exactly the same as
248 C<< My::Obj<=>VALUE >>.
249
250 =item register_package( $package, $category[, $prefix, $reversible] );
251
252 Given the package name in C<$package>, register all subroutines beginning with
253 C<$prefix> (by default an underscore: C<_>) to the comparator category in
254 C<$category>. This is how the standard comparator functions are registered. An
255 empty C<$prefix> is disallowed as C<register_package()> must be able to know
256 which subroutines to register. If C<$reversible> is passed in and it evaluates
257 to true then all comparators for this package will be reversible.
258
259 =item is_registered( $t_type[, $m_type] )
260
261 If one argument is provided, check if there is a comparator category for
262 C<$t_type>. If two arguments are provided then check if the comparator for
263 C<< $t_type<=>$m_type >> has been registered.
264
265 =item dispatch( $t_type, $m_type[, $topic, $match] )
266
267 Dispatch to the comparator for C<$t_type> and C<$m_type>, passing along
268 C<$topic> and C<$match> (defaulting to C<$Switch::Perlish::TOPIC> and
269 C<$Switch::Perlish::MATCH>, respectively).
270
271 =back
272
273 =head2 Helper subroutines
274
275 =over
276
277 =item value_cmp($t, $m)
278
279 Given two simple values try to compare them in the most natural way i.e try to
280 compare 2 numbers as numbers, 2 strings as strings and any other combination do
281 a regexp match.
282
283 =back
284
285 =head1 FURTHER INFO
286
287 =head2 Creating a new comparator
288
289 If we have a L<CGI> object and want I<smart match> it to something then we need
290 to create a new comparator. This can be implemented in whatever
291 way seems most appropriate, so for the sake of this module we will be testing
292 for the existence of a simple value in C<param()> e.g
293
294 sub cgi_comparator {
295 my($cgi, $val) = @_;
296 return defined( $cgi->param($val) );
297 }
298
299 Now that we have our comparator for C<< CGIE<lt>=>VALUE >> (the above subroutine)
300 and we know what we're comparing (a L<CGI> object and a simple value) we can
301 register it like this:
302
303 use Switch::Perlish::Smatch 'smatch';
304
305 Switch::Perlish::Smatch->register(
306 topic => 'CGI',
307 match => 'VALUE',
308 compare => \&cgi_comparator,
309 );
310
311 So we can now compare simple values with L<CGI> objects e.g
312
313 my $q = CGI->new;
314 my $check = $ARGV[0];
315 printf "%s $check in params!\n",
316 smatch($q, $check) ? 'found' : 'not found';
317
318 =head2 The default types
319
320 There are currently 8 default types, all of which have a complete set of
321 comparators implemented. These 8 types are:
322
323 =over
324
325 =item VALUE
326
327 This type covers simple values which are just strings or numbers.
328
329 =item UNDEF
330
331 This covers any C<undef>s.
332
333 =item SCALAR
334
335 This covers all C<SCALAR> references.
336
337 =item ARRAY
338
339 Covers arrays.
340
341 =item HASH
342
343 Covers hashes.
344
345 =item CODE
346
347 Covers coderefs i.e subroutines.
348
349 =item OBJECT
350
351 Covers any objects that don't have specific comparators.
352
353 =item Regexp
354
355 Covers C<Regexp> objects.
356
357 =back
358
359 =head2 How comparators compare
360
361 For info on how each comparator works see.
362 L<Switch::Perlish::Smatch::Comparators>.
363
364 =head1 TODO
365
366 =over
367
368 =item *
369
370 Add more helper subroutines for common operations default, and make them easier
371 to access.
372
373 =item *
374
375 Move into own module if people find it sufficiently useful.
376
377 =item *
378
379 Add object functionality perhaps (but who wants that?).
380
381 =item *
382
383 Maybe add inheritable comparators.
384
385 =item *
386
387 Set __ANON__ to comparator name for debugging purposes.
388
389 =item *
390
391 Add support for C<GLOB> (and possibly C<IO>) types.
392
393 =item *
394
395 Store the smatch result somewhere.
396
397 =item *
398
399 Allow for choice of which comparators are reversible in C<register_package()>.
400
401 =back
402
403 =head1 SEE. ALSO
404
405 L<Match::Smart>
406
407 L<Data::Compare>
408
409 L<Switch::Perlish>
410
411 =head1 EXPORT_OK
412
413 C<smatch> (an alias to C<match>)
414
415 C<value_cmp>
416
417 =head1 AUTHOR
418
419 Dan Brook C<< <mr.daniel.brook@gmail.com> >>
420
421 =head1 COPYRIGHT
422
423 Copyright (c) 2006, Dan Brook. All Rights Reserved. This module is free
424 software. It may be used, redistributed and/or modified under the same
425 terms as Perl itself.
426
427 =cut
« Perlish.pm ↑ Summary Perlish/Smatch/Hash.pm »