blib/lib/Module/Check_Args.pm

filter: Statementstmt 84.2% 64 / 76 Branchbran 63.3% 19 / 30 Conditioncond 80.0% 4 / 5 MC/DCmcdc 66.6% 2 / 3 Subroutinesub 86.6% 13 / 15 Podpod 100% 4 / 4 totaltotal 79.7% 106 / 133 CC 18 SCAR 13.2
CC
18
Cov
78%
import
7.0
range_argcount
5.1
atleast_argcount
4.1
CRAP 3.8
↑ Summary
1 ##==============================================================================
2 ## Module::Check_Args - a quick way to check argument counts
3 ##==============================================================================
4 ## $Id: Check_Args.pm,v 1.1 2000/11/04 18:46:06 kevin Exp $
5 ##==============================================================================
6 1 require 5.000;
7  
8 package Module::Check_Args;
9 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
10 1 ▶use Exporter ();
Subroutine BEGIN: called CC=1 SCAR=0.0
11 1 ▶use vars qw{@EXPORT @ISA $VERSION %_PROCS};
Subroutine BEGIN: called CC=1 SCAR=0.0
12 1 @ISA = qw{Exporter};
13 1 @EXPORT = qw{exact_argcount range_argcount atleast_argcount atmost_argcount};
14 1 ($VERSION) = q$Revision: 1.1 $ =~ /Revision:\s+([^\s]+)/;
15  
16 1 ▶use constant no_dieproc => "no behavior set for Module::Check_Args - 'import' never called?";
Subroutine BEGIN: called CC=1 SCAR=0.0
17  
18 =head1 NAME
19  
20 Module::Check_Args - a quick way to check argument counts for methods
21  
22 =head1 SYNOPSIS
23  
24 use Module::Check_Args;
25  
26 exact_argcount I<$argcnt>;
27  
28 range_argcount I<$minargs>, I<$maxargs>;
29  
30 atleast_argcount I<$minargs>;
31  
32 atmost_argcount I<$maxargs>;
33  
34 =head1 DESCRIPTION
35  
36 When writing a complex program, some of the hardest problems to track down
37 are subroutines that aren't called with the right arguments. Perl provides
38 a means to check this at compile time, but there is no way to do this for
39 subroutines that take a variable number of arguments or for object methods.
40 C<Module::Check_Args> provides routines that check the number of arguments
41 passed to their callers and raise an exception if the number passed doesn't
42 match the number expected. It's possible to specify that the number of
43 arguments must be exactly I<n>, at most I<n>, at least I<n>, or between
44 I<n> and I<m>.
45  
46 When using these routines from within a method, be sure to account for the
47 implicit first argument containing the object reference or class name!
48  
49 By default, the four _argcount routines are exported.
50  
51 By importing the following pseudo-symbols, you can request various
52 behaviors from C<Module::Check_Args>:
53  
54 =over 4
55  
56 =item use Module::Check_Args qw(-die);
57  
58 Specifies that an argument count mismatch is a fatal error. The message will
59 give the file and line number of the call containing the bad number of
60 arguments. This is the default.
61  
62 =item use Module::Check_Args qw(-warn);
63  
64 An argument mismatch is a warning only.
65  
66 =item use Module::Check_Args qw(-off);
67  
68 No argument-count checking is performed. The four checking routines are still
69 exported, so that you don't need to change code that contains them, but they
70 are dummy procedures.
71  
72 =back
73  
74 If you have multiple packages that use Module::Check_Args, each one can have
75 different behavior.
76  
77 =cut
78 ##------------------------------------------------------------------------------
79 ## import
80 ##------------------------------------------------------------------------------
81 0 ▶sub _dummy_proc { };
Subroutine _dummy_proc: not called CC=1 SCAR=0.0
82  
83 1 ▶sub import {
Subroutine import: called CC=5 SCAR=19.5
84 1 my $module = shift;
85 0 my @options = grep { /^-/ } @_;
86 1 ▶ die "only one -option allowed to ${module}::import\n" if @options > 1;
Branch: 1 branch
BranchTrueFalseTotal
if @options > 1 0 1 1
87 1 ▶ my $option = shift(@options) || '-die';
Condition50%1/2
shift @options || '-die'
l!l
01
MC/DC0%0/1
shift @options || '-die'
shift @options
Truth table50%1/2
A
A= shift @options
Aresult
11
00
88 0 @_ = grep { ! /^-/ } @_;
89 1 my ($calling_package, $filename, $line) = caller;
90 ##
91 ## Set up the procedures to handle various methods of reporting the error.
92 ##
93 my %subs = (
94 5 ▶ -die => sub {
Subroutine __ANON__: called CC=1 SCAR=0.0
95 5 my ($package, $filename, $line, $subroutine) = caller(2);
96 5 die "$filename($line): ", @_, "\n";
97 },
98 0 ▶ -warn => sub {
Subroutine __ANON__: not called CC=1 SCAR=6.9
99 0 my ($package, $filename, $line, $subroutine) = caller(2);
100 0 warn "$filename($line): ", @_, "\n";
101 },
102 1 -off => 1
103 );
104 die "'$option' invalid in ${module}::import from $calling_package ($filename, line $line)\n"
105 1 ▶ unless exists $subs{$option};
Branch: 1 branch
BranchTrueFalseTotal
unless exists $subs{$option} 0 1 1
106 ##
107 ## If the option is -off, export dummy subroutines that don't actually do anything.
108 ##
109 1 ▶ if ($option eq '-off') {
Branch: 1 branch
BranchTrueFalseTotal
if ($option eq '-off') { } 0 1 1
110 1 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
111 0 *{"$calling_package\::exact_argcount"} = *_dummy_proc;
112 0 *{"$calling_package\::atleast_argcount"} = *_dummy_proc;
113 0 *{"$calling_package\::atmost_argcount"} = *_dummy_proc;
114 0 *{"$calling_package\::range_argcount"} = *_dummy_proc;
115 } else {
116 1 $_PROCS{$calling_package} = $subs{$option};
117 1 unshift(@_, $module);
118 1 goto &Exporter::import;
119 }
120 }
121  
122 =head2 Routines
123  
124 =over 4
125  
126 =item exact_argcount I<$argcnt>;
127  
128 Specifies that the caller must have exactly I<$argcnt> arguments.
129  
130 =cut
131 ##------------------------------------------------------------------------------
132 ## exact_argcount
133 ##------------------------------------------------------------------------------
134 2 ▶sub exact_argcount ($) {
Subroutine exact_argcount: called CC=4 SCAR=13.9
Pod documented
135 2 ▶ my $dieproc = $_PROCS{scalar(caller)} or die no_dieproc;
Branch: 1 branch
BranchTrueFalseTotal
my $dieproc = $Module::Check_Args::_PROCS{scalar caller} or die "no behavior set for Module::Check_Args - 'import' never called?" 2 0 2
136 package DB;
137 1 ▶ use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
138 1 ▶ use vars qw(@args);
Subroutine BEGIN: called CC=1 SCAR=0.0
139 2 ▶ croak "wrong argument count to Module::Check_Args::exact_argcount" unless @_ == 1;
Branch: 1 branch
BranchTrueFalseTotal
unless @_ == 1 0 2 2
140 2 my $argcount = shift;
141 2 my (@callerdata) = caller(1);
142 2 ▶ unless (@args == $argcount) {
Branch: 1 branch
BranchTrueFalseTotal
unless (@DB::args == $argcount) 1 1 2
143 1 $dieproc->(
144 "wrong number of arguments to \&$callerdata[3] - was ",
145 scalar(@args),
146 ", should be $argcount"
147 );
148 }
149 }
150  
151 =item range_argcount I<$minargs>, I<$maxargs>;
152  
153 Specifies that the caller must have at least I<$minargs> arguments but no more
154 than I<$maxargs>.
155  
156 =cut
157 ##------------------------------------------------------------------------------
158 ## range_argcount
159 ##------------------------------------------------------------------------------
160 3 ▶sub range_argcount ($$) {
Subroutine range_argcount: called CC=5 SCAR=16.2
Pod documented
161 3 ▶ my $dieproc = $_PROCS{scalar(caller)} or die no_dieproc;
Branch: 1 branch
BranchTrueFalseTotal
my $dieproc = $Module::Check_Args::_PROCS{scalar caller} or die "no behavior set for Module::Check_Args - 'import' never called?" 3 0 3
162 package DB;
163 3 ▶ croak "wrong argument count to Module::Check_Args::range_argcount" unless @_ == 2;
Branch: 1 branch
BranchTrueFalseTotal
unless @_ == 2 0 3 3
164 3 my ($minargs, $maxargs) = @_;
165 3 my (@callerdata) = caller(1);
166 3 ▶ unless (@args >= $minargs && @args <= $maxargs) {
Branch: 1 branch
BranchTrueFalseTotal
unless (@DB::args >= $minargs and @DB::args <= $maxargs) 2 1 3
Condition100%3/3
@DB::args >= $minargs and @DB::args <= $maxargs
!ll&&!rl&&r
111
MC/DC100%2/2
@DB::args >= $minargs and @DB::args <= $maxargs
@DB::args >= $minargs @DB::args <= $maxargs
Truth table100%3/3
A and B
A= @DB::args >= $minargsB= @DB::args <= $maxargs
ABresult
0X0
100
111
167 2 $dieproc->(
168 "wrong number of arguments to \&$callerdata[3] - was ",
169 scalar(@args),
170 ", should be between $minargs and $maxargs"
171 );
172 }
173 }
174  
175 =item atleast_argcount I<$minargs>;
176  
177 Specifies that the caller must have at least I<$minargs> arguments, but can have
178 any number more than that.
179  
180 =cut
181 ##------------------------------------------------------------------------------
182 ## atleast_argcount
183 ##------------------------------------------------------------------------------
184 2 ▶sub atleast_argcount ($) {
Subroutine atleast_argcount: called CC=4 SCAR=14.0
Pod documented
185 2 ▶ my $dieproc = $_PROCS{scalar(caller)} or die no_dieproc;
Branch: 1 branch
BranchTrueFalseTotal
my $dieproc = $Module::Check_Args::_PROCS{scalar caller} or die "no behavior set for Module::Check_Args - 'import' never called?" 2 0 2
186 package DB;
187 2 ▶ croak "wrong argument count to Module::Check_Args::atleast_argcount" unless @_ == 1;
Branch: 1 branch
BranchTrueFalseTotal
unless @_ == 1 0 2 2
188 2 my $minargs = shift;
189 2 my (@callerdata) = caller(1);
190 2 ▶ unless (@args >= $minargs) {
Branch: 1 branch
BranchTrueFalseTotal
unless (@DB::args >= $minargs) 1 1 2
191 1 $dieproc->(
192 "not enough arguments to \&$callerdata[3] - was ",
193 scalar(@args),
194 ", should be at least $minargs"
195 );
196 }
197 }
198  
199 =pod
200  
201 =item atmost_argcount I<$maxargs>;
202  
203 Specifies that the caller must have at most I<$maxargs> arguments, but can have
204 any number up to that, including zero.
205  
206 =cut
207 ##------------------------------------------------------------------------------
208 ## atmost_argcount
209 ##------------------------------------------------------------------------------
210 2 ▶sub atmost_argcount ($) {
Subroutine atmost_argcount: called CC=4 SCAR=14.0
Pod documented
211 2 ▶ my $dieproc = $_PROCS{scalar(caller)} or die no_dieproc;
Branch: 1 branch
BranchTrueFalseTotal
my $dieproc = $Module::Check_Args::_PROCS{scalar caller} or die "no behavior set for Module::Check_Args - 'import' never called?" 2 0 2
212 package DB;
213 2 ▶ croak "wrong argument count to Module::Check_Args::atmost_argcount" unless @_ == 1;
Branch: 1 branch
BranchTrueFalseTotal
unless @_ == 1 0 2 2
214 2 my $maxargs = shift;
215 2 my (@callerdata) = caller(1);
216 2 ▶ unless (@args <= $maxargs) {
Branch: 1 branch
BranchTrueFalseTotal
unless (@DB::args <= $maxargs) 1 1 2
217 1 $dieproc->(
218 "too many arguments to \&$callerdata[3] - was ",
219 scalar(@args),
220 ", should be no greater than $maxargs"
221 );
222 }
223 }
224  
225 =back
226  
227 =head1 DIAGNOSTICS
228  
229 =over 4
230  
231 =item wrong argument count to Module::Check_Args::I<routine>
232  
233 One of the argument count checking routines was itself called with an invalid
234 argument count. This is always a fatal error regardless of the behavior
235 specified in the B<use> declaration.
236  
237 =item I<file>(I<line>): too many arguments to I<routine> - was %d, should be no greater than %d
238  
239 =item I<file>(I<line>): not enough arguments to I<routine> - was %d, should be at least %d
240  
241 =item I<file>(I<line>): wrong number of arguments to I<routine> - was %d, should be between %d and %d
242  
243 =item I<file>(I<line>): wrong number of arguments to I<routine> - was %d, should be %d
244  
245 I<routine> was called with an invalid number of arguments at the indicated location.
246 These messages are either fatal errors or warnings depending on the behavior specified
247 in the B<use> declaration.
248  
249 =item no behavior set for Module::Check_Args - 'import' never called?
250  
251 One of the argument count check routines was called, but no behavior
252 (-die, -warn) had ever been set. This can only happen if you use
253 something like the following combination of commands:
254  
255 use Module::Check_Args ();
256 ...
257 &Module::Check_Args::exact_argcount(3);
258  
259 Don't do that.
260  
261 =back
262  
263 =head1 SEE ALSO
264  
265 perlfunc -f caller
266  
267 =head1 AUTHOR
268  
269 Kevin Michael Vail <kevin@vailstar.com>
270  
271 =cut
272  
273 1 1;
274  
275 ##==============================================================================
276 ## $Log: Check_Args.pm,v $
277 ## Revision 1.1 2000/11/04 18:46:06 kevin
278 ## $module::import != ${module}::import
279 ##
280 ## Revision 1.0 2000/11/04 18:42:27 kevin
281 ## Initial revision
282 ##==============================================================================
↑ Summary