NAME

Module::Check_Args - a quick way to check argument counts for methods

SYNOPSIS

use Module::Check_Args;

exact_argcount $argcnt;

range_argcount $minargs, $maxargs;

atleast_argcount $minargs;

atmost_argcount $maxargs;

DESCRIPTION

When writing a complex program, some of the hardest problems to track down are subroutines that aren't called with the right arguments. Perl provides a means to check this at compile time, but there is no way to do this for subroutines that take a variable number of arguments or for object methods. Module::Check_Args provides routines that check the number of arguments passed to their callers and raise an exception if the number passed doesn't match the number expected. It's possible to specify that the number of arguments must be exactly n, at most n, at least n, or between n and m.

When using these routines from within a method, be sure to account for the implicit first argument containing the object reference or class name!

By default, the four _argcount routines are exported.

By importing the following pseudo-symbols, you can request various behaviors from Module::Check_Args:

use Module::Check_Args qw(-die);

Specifies that an argument count mismatch is a fatal error. The message will give the file and line number of the call containing the bad number of arguments. This is the default.

use Module::Check_Args qw(-warn);

An argument mismatch is a warning only.

use Module::Check_Args qw(-off);

No argument-count checking is performed. The four checking routines are still exported, so that you don't need to change code that contains them, but they are dummy procedures.

If you have multiple packages that use Module::Check_Args, each one can have different behavior.

Routines

exact_argcount $argcnt;

Specifies that the caller must have exactly $argcnt arguments.

range_argcount $minargs, $maxargs;

Specifies that the caller must have at least $minargs arguments but no more than $maxargs.

atleast_argcount $minargs;

Specifies that the caller must have at least $minargs arguments, but can have any number more than that.

atmost_argcount $maxargs;

Specifies that the caller must have at most $maxargs arguments, but can have any number up to that, including zero.

DIAGNOSTICS

wrong argument count to Module::Check_Args::routine

One of the argument count checking routines was itself called with an invalid argument count. This is always a fatal error regardless of the behavior specified in the use declaration.

file(line): too many arguments to routine - was %d, should be no greater than %d

file(line): not enough arguments to routine - was %d, should be at least %d

file(line): wrong number of arguments to routine - was %d, should be between %d and %d

file(line): wrong number of arguments to routine - was %d, should be %d

routine was called with an invalid number of arguments at the indicated location. These messages are either fatal errors or warnings depending on the behavior specified in the use declaration.

no behavior set for Module::Check_Args - 'import' never called?

One of the argument count check routines was called, but no behavior (-die, -warn) had ever been set. This can only happen if you use something like the following combination of commands:

    use Module::Check_Args ();
    ...
    &Module::Check_Args::exact_argcount(3);

Don't do that.

SEE ALSO

perlfunc -f caller

AUTHOR

Kevin Michael Vail <kevin@vailstar.com>