/ 
Scalar-Validation-0.600
River stage zero No dependents
/ Scalar::Validation

NAME

Scalar::Validation

Simple rule based validation package for scalar values

VERSION

This documentation refers to version 0.500 of Scalar::Validation

SYNOPSIS

use Scalar::Validation qw(:all);

my $int_1    = validate int_1   => Int   => 123;
my $float_1  = validate float_1 => Float => 3.1415927;

my $para_1   = par parameter_1 => -Range => [1,5] => Int => shift;

my $int_2    = validate (int_2    => -And => [Scalar => 'Int'],  123);
my $int_3    = validate (int_3    => -Or  => [Int => 'CodeRef'], 123);
my $code_ref = validate (code_ref => -Or  => [Int => 'CodeRef'], sub { 123; });

my $enum_abc = validate (parameter => -Enum => {a => 1, b => 1, c => 1}, 'c');

my $int_4    = validate (int_4   => -Optional => Int    =>                             undef);
my $int_5    = validate (int_5   => -Optional => -And   => [Scalar => Int => 0] =>     undef);
my $int_6    = validate (int_6   => -Optional => -Or    => [Int => CodeRef => 0] =>    undef);
my $enum_2   = validate (enum_2  => -Optional => -Enum  => {a => 1, b => 1, c => 1} => undef);
my $range_1  = validate (range_1 => -Optional => -Range => [1,5] => Int =>             undef);

Just checks, never dies:

is_valid(valid_1 => Int => 123);   # is valid,     returns 1;
is_valid(valid_2 => Int => 1.23);  # is not valid, returns 0;
is_valid(valid_3 => Int => 'a');   # is not valid, returns 0;
is_valid(valid_4 => Int => undef); # is not valid, returns 0;

Free defined rules or wheres only (also for validate(...))

# be careful, doesn't check that $_ is an integer!
is_valid (free_where_greater_zero => sub { $_ && $_ > 0} => 2);  # is valid, returns 1

is_valid (free_rule_greater_zero => { -as      => Int =>
                                                                              -where   => sub { $_ && $_ > 0},
                                                                              -message => sub { "$_ is not > 0" },
                                                                        }
          => 2); # is valid, returns 1

my $my_rule = { -as => Int => -where => sub { $_ && $_ > 0} => -message => sub { "$_ is not > 0" };

is_valid (free_rule_greater_zero => $my_rule => 2);              # is valid, returns 1

DESCRIPTION

This class implements a fast and flexible validation for scalars. It is implemented functional to get speed and some problems using global rules for all ;).

Dies by error message

validate (parameter => -And => [Scalar => 'Int'],  {} );
validate (parameter => -And => [Scalar => 'Int'],  [] );
validate (parameter => -And => [Scalar => 'Int'],  sub { 'abc'; });

Just check without die

print is_valid(parameter => -And => [Scalar => 'Int'],  123) ." => 123 is int\n";
print is_valid(parameter => -And => [Scalar => 'Int'],  {} ) ." => {} is no scalar\n";
print is_valid(parameter => -And => [Scalar => 'Int'],  [] ) ." => [] is no scalar\n";
print is_valid(parameter => -And => [Scalar => 'Int'],  sub { 'abc'; }) ." => sub { 'abc'; } is no scalar\n";

Get validation messages

Message store has to be localized. The only safe way to deal with recursive calls and die! So use a block like this to store messages

my @messages;
{
    local ($Scalar::Validation::message_store) = [];

    my $result = is_valid(parameter => -And => [Scalar => 'Int'],  {} );
            
    @messages = @{validation_messages()} unless $result;
}

As parameter check for indexed arguments

It can be also used a parameter check for unnamed and named parameters, see

sub create_some_polynom {
    my $max_potenz = par maximum_potenz => -Range => [1,5] => Int => shift;

    parameters_end \@_;

    # --- run sub -------------------------------------------------

    my $polynom = '';
    map { $polynom .= " + ".int (100*rand())."*x^".($max_potenz-$_); } (0..$max_potenz);

    return $polynom;
};

sub create_some_polynom_named {
    my %pars = convert_to_named_params \@_;

    my $max_potenz = npar -maximum_potenz => -Range => [1,5] => Int => \%pars;

    parameters_end \%pars;

    # --- run sub -------------------------------------------------

    my $polynom = '';
    map { $polynom .= " + ".int (100*rand())."*x^".($max_potenz-$_); } (0..$max_potenz);

    return $polynom;
};


print create_some_polynom(1)."\n";
print create_some_polynom(2)."\n";
print create_some_polynom(3)."\n";
print create_some_polynom(4)."\n";
print create_some_polynom(5)."\n";

print create_some_polynom_named(-maximum_potenz => 4);

Dies by error message

print create_some_polynom(5.5)."\n";
print create_some_polynom(6)."\n";
print create_some_polynom(6, 1)."\n";

Rules

You can and should create your own rules, i.e.

declare_rule (
    Positive =>  -as      => Int =>           # Parent rule is optional
                 -where   => sub { $_ >= 0 },
                 -message => sub { "value '$_' is not a positive integer" },
);

rule_known(Unknown  => 1); # returns 0 (false)
rule_known(Positive => 1); # returns 1 (true)

Create Own Validation Module

You should not use Scalar::Validation direct in your code.

Better is creating an own module My::Validation, that adds the rules you need and only exports the subs the developers in your project should use:

use My::Validation;

my $v_my_type = validate v_int => my_type => new MyType();

More Examples

Have a look into Validation.t to see what else is possible

LICENSE AND COPYRIGHT

Copyright (c) 2014 by Ralf Peine, Germany. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.6.0 or, at your option, any later version of Perl 5 you may have available.

DISCLAIMER OF WARRANTY

This library 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.