/ 
Params-Validate-Checks-0.01
River stage one • 3 direct dependents • 3 total dependents
/ Params::Validate::Checks

NAME

Params::Validate::Checks - Named checks for use with Params::Validate

SYNOPSIS

use Params::Validate::Checks qw<validate as>;

sub random_insult
{
  my %arg = validate @_,
  {
    name => {as 'string'},
    words => {as 'pos_int'},
    paragraphs => {as 'pos_int', default => 1},
  };

  # Do something with $arg{name}, $arg{words}, $arg{paragraphs} ...
}

DESCRIPTION

Params::Validate lets you precisely specify what are valid arguments to your functions and methods, helping to catch errors sooner and make your programs more robust. But if multiple parameters (in either the same or different subs) have the same spec it's tedious to have to repeat this. So Params::Validate::Checks provides:

  • standard, named checks for use in Params::Validate specifications

  • a way of you defining more named checks for your own re-use

Basic Use

Import validate and as, then read a function's arguments into a hash by calling the validate function. Pass it @_ and a hash-ref specifying your function's named parameters:

sub total_price {
  my %arg = validate @_, {
    unit_price => {as 'pos_int'},
    quantity => {as 'pos_int'},
  };

Each key in the hash-ref is a parameter's name; the corresponding value is specified in braces with as followed by the name of the check to apply to that parameter.

If all the checks pass then your hash will be populated with the supplied arguments.

But if there's a problem with the arguments then your function will abort with an appropriate error message. This could happen in any of these situations:

  • a compulsory argument is missing

  • an argument is supplied but its contents don't pass its check

  • an unexpected argument has been supplied

Standard Checks

These standard checks are supplied by this module:

pos_int

a positive integer, such as "42" (but not "0", "007", or "24A")

string

a single-line string that isn't just whitespace, such as "yellow spog" (but not "" or " ", nor anything with a line-break in it); note that unlike using SCALAR in Params::Validate this does permit objects which stringify to an appropriate value, such as Path::Class objects

Currently there's just those two because they're the only 'generic' checks I've needed, but it's likely more will be added -- requests welcome!

For checks specific to a particular field it makes more sense to distribute them in a separate module, especially when they depend on other modules; for example Params::Validate::Checks::Net contains some checks useful for dealing with network-related things, such as domain names and IP addresses.

More Advanced Use

All of Params::Validate's features and flexibility can be used, and for convenience any of its functions can be imported via Params::Validate::Checks, so you don't need 2 use lines. (The :all tag imports everything Params::Validate would plus as from this module.)

You can add options to individual checks, such as optional to make a parameter optional:

my %arg = validate @_,
{
  forename => {as 'string'},
  middle_name => {as 'string', optional => 1},
  surname => {as 'string'},
};

or default, which makes it optional to the caller but ensures your hash always has a value for it:

my %arg = validate @_,
{
  colour => {as 'string', default => 'red'},
  quantity => {as 'pos_int', default => 99},
};

You can mix named checks with 'one off' checks that are defined directly using Params::Validate syntax:

my %arg = validate @_,
{
  quantity => {as 'pos_int', default => 1},
  product_code => {regex => qr/^[DOSW]\d{4}\z/},
};

You can use validate_pos to validate positional parameters:

use Params::Validate::Checks qw<validate_pos as>;
my ($x, $y) = validate_pos @_, {as 'pos_int'}, {as 'pos_int', default => 0};

For details of these features and more, see Params::Validate.

Defining New Checks

It's simple to define a new check, just call Params::Validate::Checks::register with the name and functionality of the check. This can be specified as a pattern:

Params::Validate::Checks::register sort_code => qr/^\d\d-\d\d-\d\d\z/;

or a function to do the checking; the function is invoked each time an argument is being checked, with the argument passed as a parameter:

Params::Validate::Checks::register postcode => \&valid_postcode;

or as a hash-ref of a Params::Validate spec:

Params::Validate::Checks::register template => {isa => 'Template'};

While you can do this in the same file that's using the checks, the intention is to create libraries of checks -- you can put checks for things like product codes, office identifiers, and internal hostnames in a library for your organization. And checks for 'generic' things like e-mail addresses, postcodes, country codes, CSS colours, and so on can be put in modules contributed to Cpan.

Note register isn't exported (because creating checks should be rarer than using them), but you can define multiple checks in a single call, so a library of checks can -- in its entirety -- be as simple as:

package PopCorp::Params::Validate::Checks;
use Params::Validate::Checks;

Params::Validate::Checks::register
  playing_card => qr/^(?:[A2-9JQK]|10)[CDHS]\z/,
  room_number => qr/^[0-2]\.[1-9]\d*\z/,
  palindrome => sub { $_[0] eq reverse $_[0] };

register returns a true value, so it's valid to call it as the last thing in a package, as in the above example.

FUTURE PLANS

More checks, such as for other sorts of numbers, are likely to be added as uses for them are encountered.

And I suspect it'll be useful to add a way of defining a check as a list of permitted values.

CAVEATS

This module is still in its infancy; it's possible that development based on experience of using it will require making backwards-incompatible changes to its interface.

Currently there is a global list of all registered checks, so it isn't possible for two different libraries (used non-overlappingly) to declare different checks with the same name.

SEE ALSO

CREDITS

Written and maintained by Smylers <smylers@cpan.org>

Thanks to Aaron Crane for help with the design, and Ovid for spotting a bug. And of course thank you to Dave Rolsky for creating Params::Validate.

COPYRIGHT & LICENCE

Copyright 2006-2008 by Smylers.

This library is software libre; you may redistribute it and modify it under the terms of any of these licences: