| 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
Condition66%2/3
$data || ()
MC/DC50%1/2
$data || ()
$data
()
Truth table66%2/3
A || B
A= $dataB= ()
| |||||||||||||||||||||||||||||||||||
| 92 | 2 | ▶ | no warnings; | ||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||
| 93 | 4 | ▶ | if ('ANON' eq $symbol) { | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||
| 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
Condition100%2/2
ref $_ or "scalar"
MC/DC100%1/1
ref $_ or "scalar"
ref $_
Truth table100%2/2
A
A= ref $_
| |||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||
| 128 | 3 | ▶ | if ($optional) { | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||
| 136 | } elsif ($type eq 'scalar') { | ||||||||||||||||||||||||||||||||||
| 137 | 2 | ▶ | return 0 if ref $arg; | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 138 | } elsif ($type eq 'null') { | ||||||||||||||||||||||||||||||||||
| 139 | 3 | ▶ | return 0 if defined $arg; | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 140 | } elsif ($type eq 'list') { | ||||||||||||||||||||||||||||||||||
| 141 | 1 | ▶ | shift @args while @args; | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 142 | } elsif ($type eq 'hash') { | ||||||||||||||||||||||||||||||||||
| 143 | 2 | ▶ | return 0 unless scalar(@args) % 2; | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 144 | 1 | ▶ | shift @args while @args; | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||
| 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 | |||||||||||||||||||||||||||||||||||