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.