NAME

Params::Validate::Dependencies - check that the right combination of arguments is passed to a function

DESCRIPTION

Extends Params::Validate to make it easy to validate that you have been passed the correct combinations of parameters.

SYNOPSIS

This example validates that sub 'foo's arguments are of the right types, and that either we have at least one of alpha, beta and gamma, or we have both of bar amd baz:

  use Params::Validate::Dependencies qw(:all);

  sub foo {
    validate(@_,
      {
        alpha => { type => ARRAYREF, optional => 1 },
        beta  => { type => ARRAYREF, optional => 1 },
        gamma => { type => ARRAYREF, optional => 1 },
        bar   => { type => SCALAR, optional => 1 },
        baz   => { type => SCALAR, optional => 1 },
      },
      any_of(
        qw(alpha beta gamma),
        all_of(qw(bar baz)),
      )
    );
  }

HOW IT WORKS

Params::Validate::Dependencies extends Params::Validate's validate() function to support an arbitrary number of callbacks which are not associated with any one parameter. All of those callbacks are run after Params::Validate's normal validate() function. If any of them return false, then validate() will die as normal.

SUBROUTINES and EXPORTS

All of the *_of functions are exported by default in addition to those exported by default by Params::Validate. They are also available with the tag ':_of' in case you want to use them without Params::Validate. In that case you would load the module thus:

  use Params::Validate::Dependencies qw(:_of);

All of the *_of functions take a list of scalars and code-refs and return a code-ref (which is a closure over the list originally passed to the function) suitable for use in validate() or in another *_of function. All code-refs should take as their only argument a hashref of parameters to check, returning true if the parameters are good and false otherwise.

document

This takes a code-ref argument as generated by a tree of *_of calls, and spits out some documentation of it. This function is not exported.

validate

Overrides and extends Params::Validate's function of the same name.

validate_with

Overrides and extends Params::Validate's function of the same name.

The code-ref, or an array-ref of code-refs, are passed as the extra 'dependencies' argument.

exclusively

Takes a single subref as its only argument (this would normally be the results of one of the *_of functions), and returns a code-ref which returns true if the hashref it is given only contains fields mentioned in the original function or any of its children. For example ...

    validate(@_,
      exclusively(
        any_of(
          qw(alpha beta gamma),
          all_of(qw(bar baz)),
        )
      )
    );

will not tolerate arguments such as:

  bar   => ...,
  baz   => ...,
  sheep => ...

because sheep aren't mentioned in the 'any_of' and 'all_of's. Internally this uses the auto-documenter interface to interrogate the child sub. This means that if you want to use "exclusively()" with third-party extensions then they must support auto-documentation.

This function is not exported by default but can be.

none_of

Returns a code-ref which checks that the hashref it receives matches none of the options given.

You might want to use it thus:

  all_of(
    'alpha',
    none_of(qw(bar baz))
  )

to validate that 'alpha' must *not* be accompanied by 'bar' or 'baz'.

one_of

Returns a code-ref which checks that the hashref it receives matches only one of the options given.

any_of

Returns a code-ref which checks that the hashref it receives matches one or more of the options given.

all_of

Returns a code-ref which checks that the hashref it receives matches all of the options given.

LIES

Some of the above is incorrect. If you really want to know what's going on, look at Params::Validate::Dependencies::Extending.

BUGS, LIMITATIONS, and FEEDBACK

I like to know who's using my code. All comments, including constructive criticism, are welcome.

Please report any bugs either by email or at <https://github.com/DrHyde/perl-modules-Params-Validate-Dependencies/issues>.

Any incompatibility with Params::Validate will be considered to be a bug, with the exception of minor differences in error messages.

Bug reports should contain enough detail that I can replicate the problem and write a test. The best bug reports have those details in the form of a .t file. If you also include a patch I will love you for ever.

SOURCE CODE REPOSITORY

<git://github.com/DrHyde/perl-modules-Params-Validate-Dependencies.git>

<https://github.com/DrHyde/perl-modules-Params-Validate-Dependencies/>

COPYRIGHT and LICENCE

This software is free-as-in-speech software, and may be used, distributed, and modified under the terms of either the GNU General Public Licence version 2 or the Artistic Licence. It's up to you which one you use. The full text of the licences can be found in the files GPL2.txt and ARTISTIC.txt, respectively.

CONSPIRACY

This module is also free-as-in-mason.