NAME
Data::Validator - Rule based validator on type constraint system
VERSION
This document describes Data::Validator version 0.05.
SYNOPSIS
use 5.10.0;
use Data::Validator;
# for functions
sub get {
state $rule = Data::Validator->new(
uri => { isa => 'Str', xor => [qw(schema host path_query)] },
schema => { isa => 'Str', default => 'http' },
host => { isa => 'Str' },
path_query => { isa => 'Str', default => '/' },
method => { isa => 'Str', default => 'GET' },
);
my $args = $rule->validate(@_);
# ...
}
get( uri => 'http://example.com/' );
# for methods
sub method {
state $rule = Data::Validator->new(
foo => 'Str',
)->with('Method');
my($self, $args) = $rule->validate(@_);
# ...
}
Foo->method( foo => 'bar' );
# using sequenced parameters
sub seq {
state $rule = Data::Validator->new(
foo => 'Str',
)->with('Sequenced');
my $args = $rule->validate(@_);
# ...
}
seq( 'bar' ); # seq() will get { foo => 'bar' }
seq({ foo => 'bar' }); # named style are available!
# using Method and Sequenced together
sub seq_method {
state $rule = Data::Validator->new(
foo => 'Str',
)->with( 'Method', 'Sequenced');
my($self, $args) = $rule->validate(@_);
# ...
}
Foo->seq_method( 'bar' ); # seq() will get { foo => 'bar' }
DESCRIPTION
This is yet another validation library, based on Smart::Args
but less smart.
This is under development. Any API will change without notice.
Concepts
- Natural as Perl code
-
I love
Smart::Args
because it is really stylish, but it does not seem Perl-ish.Thus, I have designed
Data::Validator
in more Perl-ish way with full ofSmart::Args
functionality. - Basics on type constraint system
-
Moose's type constraint system is awesome, and so is Mouse's. In fact, Mouse's type constraints are much faster than Moose's so that you need not hesitate to use type validations.
Thus, I have made
Data::Validator
based on Mouse's type constraint system. - Pure Perl
-
Although I do not hesitate to depend on XS modules, some people think that XS modules are hard to install.
Thus, I have written
Data::Validator
in pure Perl and selected dependent modules which work in pure Perl. - Performance
-
Validators should be as fast as possible because they matter only for illegal inputs.
This is much faster than
Params::Validate
, which has an XS backend, though.
INTERFACE
Data::Validator->new( $arg_name => $rule [, ...]) :Validator
Creates a validation rule. You should cache the rules for performance.
Attributes for $rule are as follows:
isa => $type : Str|Object
-
The type of the rule, which can be a Mouse type constraint name, a class name, or a type constraint object of either Mouse or Moose (i.e. it's duck-typed).
does => $role : Str|Object
-
The type of the rule, which can be a Mouse type constraint name, a role name, or a type constraint object of either Mouse or Moose (i.e. it's duck-typed).
Note that you cannot use it with the
isa
attribute. coerce => $should_coercion : Bool
-
If false, the rule does not try to coerce when the validation fails. Default to true.
default=> $value : Any | CodeRef
-
The default value for the argument. If it is a CODE reference, it is called in scalar context as
$default->($validator, $rule, $args)
and its return value is used as a default value.Because arguments are validated in the order of definitions,
default
callbacks can rely on the previously-filled values:my $v = Data::Validator->new( foo => { default => 99 }, bar => { default => sub { my($validator, $this_rule, $args) = @_; return $args->{foo} + 1; } }, ); $v->validate(); # bar is 100 $v->validate(foo => 42); # bar is 43
Unlike Moose/Mouse's
default
, any references are allowed, but note that they are statically allocated. optional => $value : Bool
-
If true, users can omit the argument. Default to false.
xor => $exclusives : ArrayRef
-
Exclusive arguments, which users cannot pass together.
documentation => $doc : Str
-
Descriptions of the argument.
This is not yet used anywhere.
$validator->find_rule($name :Str)
Finds the rule named $name. Provided for error handling.
$validator->with(@extentions) :Validator
Applies @extentions to $validator and returns itself.
See "EXTENTIONS" for details.
$validator->validate(@args) :HashRef
Validates @args and returns a restricted HASH reference.
Restricted hashes are hashes which do not allow to access non-existing keys, so you must check a key exists
in the hash before fetching its values.
EXTENTIONS
There are extentions which changes behaviours of validate()
.
Method
Takes the first argument as an invocant (i.e. class or object instance), and returns it as the first value:
my($invocant, $args) = $rule->validate(@_);
Sequenced
Deals with arguments in sequenced style, where users should pass arguments by the order of argument rules, instead of by-name.
Note that if the last argument is a HASH reference, it is regarded as named-style arguments.
AllowExtra
Regards unknown arguments as extra arguments, and returns them as a list of name-value pairs:
my($args, %extra) = $rule->validate(@_);
NoThrow
Does not throw errors. Instead, it provides validators with the errors
attribute:
my $args = $v->validate(@_); # it never throws errors
if($v->has_errors) {
my $errors = $v->clear_errors;
foreach my $e(@{$errors}) {
# $e has 'type', 'message' and 'name'
print $e->{message}, "\n";
}
}
Croak
Does not report stack backtraces on errors, i.e. uses croak()
instead of confess()
.
DEPENDENCIES
Perl 5.8.1 or later.
BUGS
All complex software has bugs lurking in it, and this module is no exception. If you find a bug please either email me, or add the bug to cpan-RT.
SEE ALSO
AUTHOR
Fuji, Goro (gfx) <gfuji@cpan.org>
LICENSE AND COPYRIGHT
Copyright (c) 2010, Fuji Goro (gfx). All rights reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.