NAME

Params::Named - Map incoming arguments to parameters of the same name.

SYNOPSIS

use Params::Named;
use IO::All;

sub storeurl {
  my $self = shift;
  MAPARGS \my($src, $dest);
  return io($src) > io($dest);
}
$obj->storeurl(src => $url, dest => $fh);

DESCRIPTION

This module does just one thing - it maps named arguments to a subroutine's lexical parameter variables or, more specifically, any lexical variables passed into MAPARGS. Named parameters are exactly the same as a flattened hash in that they provide a list of key => value pairs. So for each key that matches a lexical variable passed to MAPARGS the corresponding value will be mapped to that variable. Here is a short example to demonstrate MAPARGS in action:

use Params::Named;
sub mapittome {
  MAPARGS \my($this, @that, %other);
  print "This is:   '$this'\n";
  print "That is:   ", join(', ', @that), "\n";
  print "The other: ", join(', ',
                            map "$_ => $other{$_}", keys %other), "\n";
}

mapittome this  => 'a simple string',
          that  => [qw/a list of items/],
          other => {qw/a hash containing pairs/};
## Or if you've got a hash.
my %args = (
  this  => 'using a hash',
  that  => [qw/is very cool/],
  other => {qw/is it not cool?/},
);
mapittome %args;

The example above illustrates the mapping of mapittome's arguments to its parameters. It will work on scalars, arrays and hashes, the 3 types of lexical values.

FUNCTIONS

MAPARGS

Given a list of variables map those variables to named arguments from the caller's argument stack (e.g @_). Taking advantage of one of Perl's more under-utilized features, passing in a list of references as created by applying the reference operator to a list will allow the mapping of compound variables (without the reference lexically declared arrays and hashes flatten to an empty list). Argument types must match their corresponding parameter types e.g foo => \@things should map to a parameter declared as an array e.g MAPARGS \my(@foo).

EXPORTS

MAPARGS

DIAGNOSTICS

No parameters mapped for '%s' at line no. '%s'

This warning is issued because none of the arguments matched any of the parameters, so no mapping is performed.

The parameter '%s' doesn't match argument type '%s'

A given parameter doesn't match it's corresponding argument's type e.g

sub it'llbreak { MAPARGS \my($foo, @bar); ... }
## This will croak() because @bar's argument isn't an array reference.
it'llbreak foo => 'this', bar => 'that';

So either the parameter or the argument needs to be updated to reflect the desired behaviour.

AUTHOR

Dan Brook <cpan@broquaint.com>

COPYRIGHT

Copyright (c) 2005, Dan Brook. All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.