NAME

Validator::Custom - Validates user input easily

SYNOPSYS

# Load module and create object
use Validator::Custom;
my $vc = Validator::Custom->new;

# Data used at validation
my $data = {age => 19, name => 'Ken Suzuki'};

# Register constraint
$vc->register_constraint(
    int => sub {
        my $value    = shift;
        my $is_valid = $value =~ /^\d+$/;
        return $is_valid;
    },
    not_blank => sub {
        my $value = shift;
        my $is_valid = $value ne '';
        return $is_valid;
    },
    length => sub {
        my ($value, $args) = @_;
        my ($min, $max) = @$args;
        my $length = length $value;
        my $is_valid = $length >= $min && $length <= $max;
        return $is_valid;
    },
);

# Rule
my $rule = [
    age => [
        'int'
    ],
    name => [
        ['not_blank',        "Name must be exists"],
        [{length => [1, 5]}, "Name length must be 1 to 5"]
    ]
];

# Validate
my $vresult = $vc->validate($data, $rule);

### Validator::Custom::Result

# Chacke if the data is valid.
my $is_valid = $vresult->is_valid;

# Error messages
my $messages = $vresult->messages;

# Error messages to hash ref
my $messages_hash = $vresult->messages_to_hash;

# Error message
my $message = $vresult->message('age');

# Invalid parameter names
my $invalid_params = $vresult->invalid_params;

# Invalid rule keys
my $invalid_rule_keys = $vresult->invalid_rule_keys;

# Raw data
my $raw_data = $vresult->raw_data;

# Result data
my $result_data = $vresult->data;

### Advanced featreus

# Corelative validation
$data = {password1 => 'xxx', password2 => 'xxx'};
$vc->register_constraint(
    same => sub {
        my $values = shift;
        my $is_valid = $values->[0] eq $values->[1];
        return [$is_valid, $values->[0]];
    }
);
$rule = [
    {password_check => [qw/password1 password2/]} => [
        ['same', 'Two password must be equal']
    ]
];
$vresult = $vc->validate($data, $rule);

# "OR" validation
$rule = [
    email => [
        'blank'
    ],
    email => [
        'not_blank',
        'emai_address'
    ]
];

# Data filter
$vc->data_filter(
    sub { 
        my $data = shift;
        
        # Convert data to hash reference
        
        return $data;
    }
);
        
# Register filter , instead of constraint
$vc->register_constraint(
    trim => sub {
        my $value = shift;
        
        $value =~ s/^\s+//;
        $value =~ s/\s+$//;
        
        return [1, $value];
    }
);

### Extending Validator:Custom

package YourValidator;
use base 'Validator::Custom';

__PACKAGE__->register_constraint(
    defined  => sub { defined $_[0] }
);

1;

DESCRIPTIONS

Validator::Custom validates user input easily.

`1. Basic usage`

At first, you load module and create object.

use Validator::Custom;
my $vc = Validator::Custom->new;

Data used in validation must be hash reference.

my $data = { 
    age => 19, 
    name => 'Ken Suzuki'
};

you can register constraint function by register_constraint().

$vc->register_constraint(
    int => sub {
        my $value    = shift;
        my $is_valid = $value =~ /^\d+$/;
        return $is_valid;
    },
    not_blank => sub {
        my $value = shift;
        my $is_valid = $value ne '';
        return $is_valid;
    },
    length => sub {
        my ($value, $args) = @_;
        my ($min, $max) = @$args;
        my $length = length $value;
        my $is_valid = $length >= $min && $length <= $max;
        return $is_valid;
    },
);

You can define validation rule, using data key(age, name) and constraint function (int, not_blank, length) and error message. Validation rule must be array reference.

my $rule = [
    age => [
        'int'
    ],
    name => [
        ['not_blank',        "Name must be exists"],
        [{length => [1, 5]}, "Name length must be 1 to 5"]
    ]
];

You can validate the data by validate(). This method return Validator::Custom::Result object.

my $vresult = $vc->validate($data, $rule);

`2. Validation result`

Validator::Custom::Result constains various information. This has the many methods.

# Chacke if the date is valid.
my $is_valid = $vresult->is_valid;

# Error messages
my $messages = $vresult->messages;

# Error messages to hash ref
my $messages_hash = $vresult->messages_to_hash;

# A error message
my $message = $vresult->message('age');

# Invalid parameter names
my $invalid_params = $vresult->invalid_params;

# Invalid rule keys
my $invalid_rule_keys = $vresult->invalid_rule_keys;

# Raw data
my $raw_data = $vresult->raw_data;

# Result data
my $result_data = $vresult->data;

I show some examples.

Example1: Get error messages

unless ($vresult->is_valid) {
    my $messages = $vresult->messages;
    
    # Do something
}

Example2: Get error messages as hash reference

unless ($vresult->is_valid) {
    my $messages = $vresult->messages_to_hash;

    # Do something
}

Example3: Combination with HTML::FillInForm

unless ($vresult->is_valid) {
    
    my $html = get_something_way();
    
    # Fill in form
    $html = HTML::FillInForm->fill(
        \$html, $vresult->raw_data,
        ignore_fields => $vresult->invalid_params
    );
    
    # Do something
}

`3. Advanced features`

Validator:Custom provide 'OR' validation. Key is written repeatedly in 'OR' validation.

$rule = [
    email => [
        'blank'
    ],
    email => [
        'not_blank',
        'emai_address'
    ]
];

If data is not hash reference, you can converted data to hash reference by data_filter().

$vc->data_filter(
    sub { 
        my $data = shift;
        
        # Convert data to hash reference
        
        return $data;
    }
);

`4. Specification of constraint function`

Constraint function receive three arguments, 1. value of data, 2. argument of rule, 3. Validator::Custom object.

And this function must return bool value to check if the value is valid.

# Register constraint
$vc->register_constraint(
    consrtaint_name => sub {
        my ($value, $args, $vc) = @_;
        
        # Do something
        
        return $is_valid;
    }
)

In the following data, 1. value of data is 'Ken Suzuki'. 2. argument of rule is [1, 5].

# Data
my $data = {name => 'Ken Suzuki'};

# Rule
# Rule
my $rule = [
    name => [
        {length => [1, 5]}
    ]
];

In case corelative validation, values is packed to array reference, 1. value of data is ['xxx', 'xxx'].

$data = {password1 => 'xxx', password2 => 'xxx'};

$rule = [
    {password_check => [qw/password1 password2/]} => [
        ['duplication', 'Two password must be equal']
    ]
];

Constraint function can be return converted value. If you return converted value, you must return array reference, first argument is bool value to check if the value is valid, second argument is converted value.

$vc->register_constraint(
    trim => sub {
        my $value = shift;
        
        $value =~ s/^\s+//;
        $value =~ s/\s+$//;
        
        return [1, $value];
    }
);

`5. Extend Validator::Custom`

Validator::Custom is easy to extend. You can register constraint functions to Your class by register_constraint.

package YourValidator;
use base 'Validator::Custom';

__PACKAGE__->register_constraint(
    defined  => sub { defined $_[0] }
);

1;

Validator::Custom::Trim, Validator::Custom::HTMLForm is good examples.

ATTRIBUTES

`constraints`

Constraint functions

$vc          = $vc->constraints(\%constraints);
$constraints = $vc->constraints;

`error_stock`

Validation error is stocked or not.

$vc          = $vc->error_stock(1);
$error_stock = $vc->error_stcok;

If error_stock is set to 1, all validation error is stocked.

If error_stock is set 0, Validation is finished after one error is occured. This is faster than all error is stocked.

Default to 1.

`data_filter`

Data filter

$vc     = $vc->data_filter($filter);
$filter = $vc->data_filter;

If data is not hash reference, you can convert the data to hash reference.

$vc->data_filter(
    sub {
        my $data = shift;
        
        # Convert data to hash reference.
        
        return $data;
    }
)

`rule`

Validation rule

$vc   = $vc->rule($rule);
$rule = $vc->rule;

Validation rule has the following syntax.

# Rule syntax
my $rule = [                          # 1. Validation rule is array ref
    key1 => [                         # 2. Constraints is array ref
        'constraint1_1',              # 3. Constraint is string
        ['constraint1_2', 'error1_2'],#      or arrya ref (error message)
        {'constraint1_3' => 'string'} #      or hash ref (arguments)
          
    ],
    key2 => [
        {'constraint2_1'              # 4. Argument is string
          => 'string'},               #
        {'constraint2_2'              #     or array ref
          => ['arg1', 'arg2']},       #
        {'constraint1_3'              #     or hash ref
          => {k1 => 'v1', k2 => 'v2'}}#
    ],
    key3 => [                           
        [{constraint3_1 => 'string'}, # 5. Combination argument
         'error3_1' ]                 #     and error message
    ],
    { key4 => ['key4_1', 'key4_2'] }  # 6. Multi key validation
        => [
            'constraint4_1'
           ],
    key5 => [
        '@constraint5_1'              # 7. array's items validation
    ]
];

`shared_rule EXPERIMENTAL`

Shared rule. Shared rule is added the head of normal rule in validation.

$vc          = $vc->shared_rule(\@rule);
$shared_rule = $vc->shared_rule;

Example

$vc->shared_rule([
    ['defined',   'Must be defined'],
    ['not_blank', 'Must be not blank']
]);

`syntax`

Validation rule syntax

$vc     = $vc->syntax($syntax);
$syntax = $vc->syntax;

MEHTODS

`new`

Create Validator::Custom object.

$vc = Validator::Costom->new;
$vc = Validator::Costom->new(%attributes);
$vc = Validator::Costom->new(\%attributes);

`register_constraint`

$vc->register_constraint(%constraint);
$vc->register_constraint(\%constraint);

Example:

$vc->register_constraint(
    int => sub {
        my $value    = shift;
        my $is_valid = $value =~ /^\-?[\d]+$/;
        return $is_valid;
    },
    ascii => sub {
        my $value    = shift;
        my $is_valid = $value =~ /^[\x21-\x7E]+$/;
        return $is_valid;
    }
);

`validate`

Validate data.

$vresult = $vc->validate($data, $rule);
$vresult = $vc->validate($data);

If the rule is ommited, attribute's rule is used,

This method return Validator::Custom::Result object.

STABILITY

This module is stable. The following attribute and method keep backword compatible in the future.

# Validator::Custom
constraints
error_stock
data_filter
rule
syntax

new
register_constraint
validate

# Validator::Custom::Result
data
raw_data
error_infos

is_valid
messages
message
messages_to_hash
invalid_params
invalid_rule_keys
error_reason
add_error_info
remove_error_info

(deprecated) errors
(deprecated) errors_to_hash
(deprecated) error
(deprecated) invalid_keys

AUTHOR

Yuki Kimoto, <kimoto.yuki at gmail.com>

http://github.com/yuki-kimoto/Validator-Custom

COPYRIGHT & LICENCE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

To install Validator::Custom, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Validator::Custom

CPAN shell

perl -MCPAN -e shell
install Validator::Custom

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSYS

DESCRIPTIONS

1. Basic usage

2. Validation result

3. Advanced features

4. Specification of constraint function

5. Extend Validator::Custom

ATTRIBUTES

constraints

error_stock

data_filter

rule

shared_rule EXPERIMENTAL

syntax