PDL::NamedArgs - Perl extension for named & unamed arguments
with optional default values
use PDL::NamedArgs;
PDL::NamedArgs (currently) exports one main function which aids in the processing of function arguments. The key differentiators with this module in comparison to others on CPAN is that it allows any combination of named & unnamed arguments while also providing optional support for default values. I like to think of it as varargs on steroids...
parseArgs($funcDef,@_)
$funcDef - Function definition that lists all arguments
(In order!!) with default values, separated
by either space or comma.
Examples "x min max" or "x,min=0,max=10"
@_ - Arguments to parse, subject to $funcDef
Returns ($result,%named)
$status - Result of parsing. 0 if ok, otherwise set
to error message
%named - Hash of argument names set to appropriate
values after argument parsing
The goal of this utility function is to allow more flexibility with how passed arguments are handled when calling a function. I guess the best way to describe this is to give an example.
Consider a function with following abstract prototype pbinom(q, size, prob, lower_tail=1, log_p=0)
In a language such as R you could call this function in any of the following formats and receive the exact same result.
pbinom(.5, 50, 3,1,1) # All arguments specified
pbinom(.5,size=50,3,log_p=1) # lower_tail set to default value
# and using named values
pbinom(prob=3,q=.5,size=50) # Using default values, named values
# & mixing up the order
We can achieve almost the same capabilties of R in perl by using the parseArgs function for parsing arguments and by changing the named variable syntax to name=>value.
The $funcDef for pbinom function would be 'q, size, prob, lower_tail=1, log_p=0' and an example implementation of pbinom using parseArgs might look like
sub pbinom
{
my($status,%argHash)=
parseArgs('q, size, prob, lower_tail=1, log_p=0'
,@_);
die ("pbinom error\n$status\n") if $status;
print "(q, size, prob, lower_tail, log_p) = ";
print "($argHash{q}, $argHash{size}, $argHash{prob},
$argHash{lower_tail}, $argHash{log_p})\n";
}
We could then call pbinom in perl by any of the following equivalent methods
pbinom(.5, 50, 3,1,0); # All arguments specified
pbinom(.5,size=>50,3,log_p=>0); # lower_tail set to default value
# and using named values
pbinom(prob=>3,q=>.5,size=>50); # Using default values, named values
# & mixing up the order
All argument names are set to lowercase as a way to allow case insensitivity, thus pbinom(PROB=>3,q=>.5,SiZe=>50) would also work, but the returned hash would only have keys that are lowercase
Priority of argument assignment
1. Named argument
2. Unnamed ordered argument
3. Default argument values
John Cavanaugh, <cavanaug@users.sourceforge.net>
perl.
