blib/lib/Attribute/Args.pm

filter: Statementstmt 100% 57 / 57 Branchbran 97.5% 39 / 40 Conditioncond 80.0% 4 / 5 MC/DCmcdc 66.6% 2 / 3 Subroutinesub 100% 12 / 12 Podpod 0.0% 0 / 4 totaltotal 94.2% 114 / 121 CC 24 SCAR 22.7
CC
24
Cov
98%
check_types
17.0
check
5.0
ARGS
4.0
CRAP 9.7
↑ Summary
1 package Attribute::Args;
2  
3 2 our $VERSION = '0.06';
4  
5 2 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 2 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
7 2 ▶use Attribute::Handlers;
Subroutine BEGIN: called CC=1 SCAR=0.0
8  
9 =head1 NAME
10  
11 Attribute::Args - check subroutine param types
12  
13 =head1 SYNOPSIS
14  
15 use Attribute::Args;
16  
17 sub foo :ARGS('scalar', 'HASH') {
18 my ($scalar, $hashref) = @_;
19 # code
20 }
21  
22 foo(42, { 'key' => 'value' }); # good
23 foo(['array', 'elements']); # bad
24  
25 =head1 OVERVIEW
26  
27 :ARGS() attribute wraps method and adds runtime type checks for method calls. dies whenever the parameters dont match.
28  
29 =head1 SUPPORTED TYPES
30  
31 =head2 any
32  
33 parameter of any type. useful for defining subs that can accept different types for some parameters.
34  
35 =head2 scalar
36  
37 scalar value. can be null. cannot be ref.
38  
39 =head2 null
40  
41 does not accept anything except undef.
42  
43 =head2 list
44  
45 accepts array. can only be the last param. must have at least one element. can be null. use the 'optional' modifier to declare an array that can be empty.
46  
47 =head2 hash
48  
49 same as list, but is also checked for parity. must have at least one key/value pair. can be null.
50  
51 =head2 any other type
52  
53 other values are treated as refs. e.g. 'ARRAY', 'HASH', 'Class::Name', etc. for classes also isa() is checked to figure out if the actual parameters class is inherited from the requested one. cannot be null.
54  
55 =head1 TYPE MODIFIERS
56  
57 currently the only modifier is the 'optional' modifier. it is denoted by a question mark after the type.
58  
59 sub foo :ARGS('scalar', 'scalar?') { ... }
60  
61 foo(42, 29); # good
62 foo(42); # good
63  
64 =head1 MANUAL CHECK
65  
66 for anonymous subs and other special cases manual type check can be used:
67  
68 sub foo {
69 my ($x, %y) = Attribute::Args::check(['scalar', 'hash?'], \@_);
70 # ...
71 }
72  
73 =head1 CAVEATS
74  
75 in some modules Attribute::Handlers, that is used in Attribute::Args, goes crazy and thinks that all subs are anonymous. you will have to use manual check for them.
76  
77 Attribute::Args distinguishes between null values and non-existing ones. you cannon pass null for optional param if it does not accept one.
78  
79 list or hash can only be the last param. whenever is is found it takes all remaining args as it's elements and anything after the list will die as if it wasnt specified.
80  
81 =cut
82  
83 2 ▶sub import {
Subroutine import: called CC=1 SCAR=0.0
84 2 my $caller = caller;
85 2 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
86 2 push @{"${caller}::ISA"}, __PACKAGE__;
87 }
88  
89 4 ▶sub ARGS :ATTR {
Subroutine ARGS: called CC=4 SCAR=13.9
Pod undocumented
90 4 my ($package, $symbol, $ref, $attr, $data, $phase) = @_;
91 4 ▶ $data = [ $data || () ] unless 'ARRAY' eq ref $data;
Branch: 1 branch
BranchTrueFalseTotal
unless "ARRAY" eq ref $data 3 1 4
Condition66%2/3
$data || ()
l!l&&r!l&&!r
102
MC/DC50%1/2
$data || ()
$data ()
Truth table66%2/3
A || B
A= $dataB= ()
ABresult
1X1
011
000
92 2 ▶ no warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
93 4 ▶ if ('ANON' eq $symbol) {
Branch: 1 branch
BranchTrueFalseTotal
if ("ANON" eq $symbol) 1 3 4
94 1 die sprintf 'trying to wrap anonymous method in %s', $package;
95 }
96 3 ▶ *$symbol = sub { return Attribute::Args::wrapper($data, $symbol, $ref, @_) };
Subroutine __ANON__: called CC=1 SCAR=0.0
97 2 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
98  
99 1 ▶sub wrapper {
Subroutine wrapper: called CC=1 SCAR=0.0
Pod undocumented
100 1 my ($data, $symbol, $original, @p) = @_;
101 1 Attribute::Args::check($data, \@p, *$symbol);
102 1 return &$original(@p);
103 }
104  
105 17 ▶sub check {
Subroutine check: called CC=5 SCAR=16.1
Pod undocumented
106 17 my ($d, $p, $s) = @_;
107 17 ▶ unless ($s) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($s) 16 1 17
108 16 my @caller = caller 1;
109 16 $s = sprintf '*%s::%s', $caller[0], $caller[3];
110 }
111 die sprintf
112 'expected %s(%s), but got %s(%s) instead',
113 $s,
114 join(', ', @$d),
115 $s,
116 17 ▶ join(', ', map { defined($_) ? ref || 'scalar' : 'null' } @$p)
Branch: 2 branches
BranchTrueFalseTotal
unless check_types($p, $d) 7 10 17
defined $_ ? : 5 1 6
Condition100%2/2
ref $_ or "scalar"
l!l
14
MC/DC100%1/1
ref $_ or "scalar"
ref $_
Truth table100%2/2
A
A= ref $_
Aresult
11
00
117 unless Attribute::Args::check_types($p, $d);
118 10 return @$p;
119 }
120  
121 17 ▶sub check_types {
Subroutine check_types: called CC=17 SCAR=28.3
Pod undocumented
122 17 my ($xargs, $xtypes) = @_;
123 17 my @args = @$xargs;
124 17 my @types = @$xtypes;
125 17 foreach my $type (@types) {
126 15 my $optional = $type =~ s/\?$//;
127 15 ▶ if (!@args) {
Branch: 1 branch
BranchTrueFalseTotal
unless (@args) 3 12 15
128 3 ▶ if ($optional) {
Branch: 1 branch
BranchTrueFalseTotal
if ($optional) { } 1 2 3
129 1 next;
130 } else {
131 2 return 0;
132 }
133 }
134 12 my $arg = shift @args;
135 12 ▶ if ($type eq 'any') {
Branch: 7 branches
BranchTrueFalseTotal
if ($type eq 'any') { } 1 11 12
elsif ($type eq 'scalar') { } 2 9 11
elsif ($type eq 'null') { } 3 6 9
elsif ($type eq 'list') { } 1 5 6
elsif ($type eq 'hash') { } 2 3 5
elsif ($type eq ref $arg) { } 1 2 3
elsif (UNIVERSAL::isa($arg, $type)) { } 1 1 2
136 } elsif ($type eq 'scalar') {
137 2 ▶ return 0 if ref $arg;
Branch: 1 branch
BranchTrueFalseTotal
if ref $arg 1 1 2
138 } elsif ($type eq 'null') {
139 3 ▶ return 0 if defined $arg;
Branch: 1 branch
BranchTrueFalseTotal
if defined $arg 1 2 3
140 } elsif ($type eq 'list') {
141 1 ▶ shift @args while @args;
Branch: 1 branch
BranchTrueFalseTotal
@args and do { shift @args } 0 1 1
142 } elsif ($type eq 'hash') {
143 2 ▶ return 0 unless scalar(@args) % 2;
Branch: 1 branch
BranchTrueFalseTotal
unless scalar(@args) % 2 1 1 2
144 1 ▶ shift @args while @args;
Branch: 1 branch
BranchTrueFalseTotal
@args and do { shift @args } 1 1 2
145 } elsif ($type eq ref $arg) {
146 } elsif (UNIVERSAL::isa($arg, $type)) {
147 } else {
148 1 return 0;
149 }
150 }
151 11 ▶ return @args ? 0 : 1;
Branch: 1 branch
BranchTrueFalseTotal
@args ? : 1 10 11
152 }
153  
154 2 1;
155  
156 =head1 AUTHOR
157  
158 Alex Alexandrov, C<< <swined at cpan.org> >>
159  
160 =head1 BUGS
161  
162 Please report any bugs or feature requests to
163 C<bug-attribute-args at rt.cpan.org>, or through the web interface at
164 L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Attribute-Args>.
165 I will be notified, and then you'll automatically be notified of progress on
166 your bug as I make changes.
167  
168 =head1 SUPPORT
169  
170 You can find documentation for this module with the perldoc command.
171  
172 perldoc Attribute::Args
173  
174 You can also look for information at:
175  
176 =over 4
177  
178 =item * AnnoCPAN: Annotated CPAN documentation
179  
180 L<http://annocpan.org/dist/Attribute-Args>
181  
182 =item * CPAN Ratings
183  
184 L<http://cpanratings.perl.org/d/Attribute-Args>
185  
186 =item * RT: CPAN's request tracker
187  
188 L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Attribute-Args>
189  
190 =item * Search CPAN
191  
192 L<http://search.cpan.org/dist/Attribute-Args>
193  
194 =back
195  
196 =head1 COPYRIGHT & LICENSE
197  
198 Copyright 2009 Alex Alexandrov, all rights reserved.
199  
200 This program is free software; you can redistribute it and/or modify it
201 under the same terms as Perl itself.
202  
203 =cut
204  
↑ Summary