NAME

Params::Validate::Aggregated - separate aggregated parameters for functions

SYNOPSIS

  use Params::Validate qw[ :all ];
  use Params::Validate::Aggregated qw[ pv_disagg ];

  my %spec;

  $spec{func1} = { foo => { type => ARRAYREF },
                   bar => { type => SCALAR } };
  sub func1 { my %args = validate( @_, $spec{func1}  };

  $spec{func2} = { goo => { type => ARRAYREF, optional => 1 },
                   loo => { type => SCALAR } };
  sub func2 { my %args = validate( @_, $spec{func2}  };

  $spec{func} = { snack => 1, bar => 1 };
  sub func {

      my ( $agg, $xtra ) = pv_disagg( params => \@_, spec => \%spec);
      die( "extra arguments passed to func\n" ) if %$xtra;

      # the @{[]} ugliness is because validate is prototyped to require
      # an array as the first argument.
      my %aggs = validate(@{[$aggs->func]}, $spec{func} );

      func1( $agg->func1 );
      func2( $agg->func2 );
  }
  func( foo => 'f', bar => 'b', snack => 's', goo => 'g', loo => 'l' );

DESCRIPTION

When a function passes named parameters through to other functions, it can be tedious work to separate out parameters specific to each function.

Params::Validate::Aggregated::pv_disagg simplifies this, separating out parameter sets from an input list of parameters, using Params::Validate named parameter specifications to identify the sets. It takes into account any key normalization routines, and uses Data::Alias to ensure that there is no duplication of the input data. It can also handle the more complex situations were validate_with is used.

INTERFACE

pv_disagg

   ( $agg, $xtra ) = pv_disagg( params => \@params,
                                spec   => \%specs,
                                with   => \%with,
                                \%opts );

Separate aggregated parameters into sets based upon Params::Validate specifications for named parameters.

The input parameters are passed in @params, which has the same structure as the parameter list passed to Params::Validate::validate() and Params::Validate::validate_with().

The sets of Params::Validate specifications are passed via %spec and %with, whose keys are used to label the output parameter sets. %spec's values are hashes as would be passed to Params::Validate::validate(); %with's values are those that would be passed to Params::Validate::validate_with(). Internally the sets specified with %spec are merged with those specified by %with. The %opts parameter may contain Params::Validate options which will be added to the specification sets passed in %spec.

An output hash is created for each specification set and contains only the input parameters specific to the set. Parameter names are normalized before being compared if specifications use normalize_keys. The keys used in the output hash are the original keys in the input list.

The output hashes are returned in $agg, which is a hash keyed off of the set names. The parameter values are aliased (via Data::Alias) to the values in @params to avoid copying.

If the allow_extra option was not true for any of the specification sets, then any input parameters in @params which did not appear in a specification set are returned in the $xtra hash. If allow_extra was true for any of the sets, then $xtra will be empty.

$agg is blessed into the Params::Validate::Aggregated class and provides accessors for each set. When called in a list context, the accessors return the hash directly; when called in scalar context they return a hash reference:

    %hash = $agg->func1;
    $hashref = $agg->func2;

DIAGNOSTICS

no specs for set %s

There were no specifications provided for the named set.

CONFIGURATION AND ENVIRONMENT

Params::Validate::Aggregated requires no configuration files or environment variables.

DEPENDENCIES

Params::Validate, Data::Alias

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests to bug-params-validate-aggregate@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Params-Validate-Aggregated.

SEE ALSO

LICENSE AND COPYRIGHT

Copyright (c) 2011 The Smithsonian Astrophysical Observatory

Params::Validate::Aggregated is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

AUTHOR

Diab Jerius <djerius@cpan.org>