NAME

Validator::Custom - Data validator basic class

SYNOPSYS

# Load module
use Validator::Custom;

# Create
my $vc = Validator::Custom->new;

# Data
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;
    },
);

# Validation 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 vresult 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;

### 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 is data validator. Validator::Custom help you to check if the data is valid.

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

Data is hash reference.

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

Constraint function registered by register_constraint() method.

# Register constraint function
$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;
    },
);

Validation rule is array reference. Message can be defined if needed.

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

Constraints section must be array reference if constraint is only the one.

# Wrong!
my $rule = [
    age => 'int' # Constraint section must be array reference!
    name => [
        ['not_blank',        "Name must be exists"],
        [{length => [1, 5]}, "Name length must be 1 to 5"]
    ]
];

validate() method validate data, and return Validator::Custom::Result object.

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

Validator::Custom::Result has the following methods.

### Validator::Custom::Result

# Chacke if the vresult 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;

The following is Validator::Custom::Result examples.

Example1:

#  Get ordered 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 L<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
}

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

# "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() method.

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

Constraint function specification

Constraint function receive three arguments, value of data, arguments of rule, and Validator::Custom object.

Constraint function must be return 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;
    }
)

Value is like 19, 'Ken Suzuki' in the data.

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

In case corelative validation, multi values is paccked to array reference, so first argument of constraint function is ['xxx', 'xxx'].

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

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

Second argument is arguments of the rule. It is specified in the rule, like [1, 5].

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

Constraint function can be also return converted value. If you return converted value, you must return array reference, which first argument is the one for checking if the value is valid, second argument is converted value.

# 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

Validator::Custom is easy to extend. You can register constraint functions to your class.

### Extending Validator:Custom

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`

Validation

$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

errors(DEPRECATED)
errors_to_hash(DEPRECATED)
error(DEPRECATED)
invalid_keys(DEPRECATED)

AUTHOR

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

Validator::Custom is developed on 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

Constraint function specification

Extending Validator::Custom

ATTRIBUTES

constraints

error_stock

data_filter

rule

shared_rule EXPERIMENTAL

syntax