view release on metacpan or  search on metacpan

lib/Data/Validator.pm  view on Meta::CPAN

=item 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 check types.

Thus, I have made C<Data::Validator> on Mouse's type constraint system.

=item 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 C<Data::Validator> in pure Perl and selected dependent
modules which work in pure Perl.

=item Performance

Validators should be as fast as possible because they matter only for illegal
inputs. Otherwise, one would want something like I<no validation> option.

This is much faster than C<Params::Validate>, which has an XS backend, though.

=back

=head1 INTERFACE

=head2 C<< Data::Validator->new( $arg_name => $rule [, ...]) :Validator >>

Creates a validation rule. You should cache the rules for performance.

Attributes for I<$rule> are as follows:

=over

=item C<< 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).

=item C<< 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 C<isa> attribute.

=item C<< coerce => $should_coercion : Bool >>

If false, the rule does not try to coerce when the validation fails.
Default to true.

=item C<< default=> $value : Any | CodeRef >>

The default value for the argument.
If it is a CODE reference, it is called in scalar context as
C<< $default->($validator, $rule, $args) >> and its return value
is used as a default value.

Because arguments are validated in the order of definitions, C<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 C<default>, any references are allowed, but note that
they are statically allocated.

=item C<< optional => $value : Bool >>

If true, users can omit the argument. Default to false.

=item C<< xor => $exclusives : ArrayRef >>

Exclusive arguments, which users cannot pass together.

=item C<< documentation => $doc : Str >>

Descriptions of the argument.

This is not yet used anywhere.

=back

=head2 C<< $validator->find_rule($name :Str) >>

Finds the rule named I<$name>. Provided for error handling.

=head2 C<< $validator->with(@extensions) :Validator >>

Applies I<@extensions> to I<$validator> and returns itself.

See L</EXTENSIONS> for details.

=head2 C<< $validator->validate(@args) :HashRef >>

Validates I<@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 C<exists> in the hash before fetching its values.

=head1 EXTENSIONS

There are extensions which changes behaviours of C<validate()>.

=head2 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(@_);

=head2 SmartSequenced