++ed by:

2 non-PAUSE users.

Yuki Kimoto

NAME

Validator::Custom - Validates user input easily

SYNOPSYS

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

    my $data = {age => 19, name => 'Ken Suzuki'};
    
    my $rule = [
        age => {message => 'age must be integer'} => [
            'not_blank',
            'int'
        ],
        name => {message => 'name must be string. the length 1 to 5'} => [
            'not_blank',
            {length => [1, 5]}
        ],
        price => [
            'not_blank',
            'int'
        ]
    ];
    
    my $result = $vc->validate($data, $rule);

    unless ($result->is_ok) {
        if ($result->has_missing) {
            my $missing_params = $result->missing_params;
        }
        
        if ($result->has_invalid) {
            my $messages = $result->messages_to_hash;
        }
    }
    

DESCRIPTION

Validator::Custom validates user input. The features are the following ones.

  • Can set messages for each parameter when data has invalid parameter. The order of messages is keeped, and also can set messages for each reason.

  • Can register constraint functions or filter functions. And useful constraint and filter is registered by default, such as not_blank, int, trim, etc.

  • Support OR condition validation, negativate validation, array validation,

See Validator::Custom::Guides to know usages of Validator::Custom.

ATTRIBUTES

constraints

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

Constraint functions.

data_filter

    my $filter = $vc->data_filter;
    $vc        = $vc->data_filter(\&data_filter);

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

error_stock

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

If error_stock is set to 1, all validation error is stocked. If error_stock is set 0, Validation is finished soon after a error occur.

Default to 1.

rule

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

Rule for validation. Validation rule has the following syntax.

    # Rule syntax
    my $rule = [                              # 1 Rule is array ref
        key => [                              # 2 Constraints is array ref
            'constraint',                     # 3 Constraint is string
            {'constraint' => 'args'}          #     or hash ref (arguments)
            ['constraint', 'err'],            #     or arrya ref (message)
        ],
        key => [                           
            [{constraint => 'args'}, 'err']   # 4 With argument and message
        ],
        {key => ['key1', 'key2']} => [        # 5.1 Multi-parameters validation
            'constraint'
        ],
        {key => qr/^key/} => [                # 5.2 Multi-parameters validation
            'constraint'                              using regular expression
        ],
        key => [
            '@constraint'                     # 6 Multi-values validation
        ],
        key => {message => 'err', ... } => [  # 7 With options
            'constraint'
        ],
        key => [
            '!constraint'                     # 8 Negativate constraint
        ],
        key => [
            'constraint1 || constraint2'      # 9 "OR" condition
        ],
    ];

syntax

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

Syntax of rule.

METHODS

Validator::Custom inherits all methods from Object::Simple and implements the following new ones.

(experimental) js_fill_form_button

    my $js_code = $self->js_fill_form_button(
        mail => '[abc]{3}@[abc]{2}.com,
        title => '[pqr]{5}'
    );

Create button javascript source code to fill form at random using pattern like regular expression. And checkbox radio group and list box also is automatically selected. This help you to input form in tests.

Note that this methos require JSON module.

validate

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

Validate the data. Return value is Validator::Custom::Result object. If the rule of second arument is ommited, The value of rule attribute is used for validation.

register_constraint

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

Register a constraint function or filter function.

    $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;
        },
        trim => sub {
            my $value = shift;
            $value =~ s/^\s+//;
            $value =~ s/\s+$//;
            
            return [1, $value];
        }
    );

If you register filter function, you must return array reference, which contain [IS_VALID_OR_NOT, FILTERED_VALUE].

(deprecated) shared_rule

This method is now deprecated because I know in almost all case We specify a constraint for each paramters.

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

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

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

CONSTRAINTS

ascii

    my $data => {name => 'Ken'};
    my $rule = [
        name => [
            'ascii'
        ]
    ];

Ascii.

between

    my $data = {age => 19};
    my $rule = [
        age => [
            {between => [1, 20]} # (1, 2, .. 19, 20)
        ]
    ];

Between A and B.

blank

    my $data => {name => ''};
    my $rule = [
        name => [
            'blank'
        ]
    ];

Blank.

decimal

    my $data = {num1 => '123.45678', num2 => '1.45'};
    my $rule => [
        num1 => [
            'decimal'
        ],
        num2 => [
            {'decimal' => [1, 2]}
        ]
    ];

Decimal. You can specify maximus digits number at before and after '.'.

defined

    my $data => {name => 'Ken'};
    my $rule = [
        name => [
            'defined'
        ]
    ];

Defined.

duplication

    my $data = {mail1 => 'a@somehost.com', mail2 => 'a@somehost.com'};
    my $rule => [
        [qw/mail1 mail2/] => [
            'duplication'
        ]
    ];

Check if the two data are same or not.

equal_to

    my $data = {price => 1000};
    my $rule = [
        price => [
            {'equal_to' => 1000}
        ]
    ];

Numeric equal comparison.

greater_than

    my $data = {price => 1000};
    my $rule = [
        price => [
            {'greater_than' => 900}
        ]
    ];

Numeric "greater than" comparison

http_url

    my $data = {url => 'http://somehost.com'};
    my $rule => [
        url => [
            'http_url'
        ]
    ];

HTTP(or HTTPS) URL.

int

    my $data = {age => 19};
    my $rule = [
        age => [
            'int'
        ]
    ];

Integer.

in_array

    my $data = {food => 'sushi'};
    my $rule = [
        food => [
            {'in_array' => [qw/sushi bread apple/]}
        ]
    ];

Check if the values is in array.

length

    my $data = {value1 => 'aaa', value2 => 'bbbbb'};
    my $rule => [
        value1 => [
            {'length' => 3}
        ],
        value2 => [
            {'length' => [2, 5]} # 'bb' to 'bbbbb'
        ]
    ];

Length of the value.

less_than

    my $data = {num => 20};
    my $rule = [
        num => [
            {'less_than' => 25}
        ]
    ];

Numeric "less than" comparison.

not_blank

    my $data = {name => 'Ken'};
    my $rule = [
        name => [
            'not_blank' # Except for ''
        ]
    ];

Not blank.

not_defined

    my $data = {name => 'Ken'};
    my $rule = [
        name => [
            'not_defined'
        ]
    ];

Not defined.

not_space

    my $data = {name => 'Ken'};
    my $rule = [
        name => [
            'not_space' # Except for '', ' ', '   '
        ]
    ];

Not contain only space characters.

space

    my $data = {name => '   '};
    my $rule = [
        name => [
            'space' # '', ' ', '   '
        ]
    ];

White space or empty stirng.

uint

    my $data = {age => 19};
    my $rule = [
        age => [
            'uint'
        ]
    ];

Unsigned integer.

regex

    my $data = {num => '123'};
    my $rule => [
        num => [
            {'regex' => qr/\d{0,3}/}
        ]
    ];

Match a regular expression.

selected_at_least

    my $data = {hobby => ['music', 'movie' ]};
    my $rule => [
        hobby => [
            {selected_at_least => 1}
        ]
    ];

Selected at least specified count item. In other word, the array contains at least specified count element.

FILTERS

merge

    my $data = {name1 => 'Ken', name2 => 'Rika', name3 => 'Taro'};
    my $rule = [
        {merged_name => ['name1', 'name2', 'name3']} => [
            'merge' # KenRikaTaro
        ]
    ];

Merge the values.

shift

    my $data = {names => ['Ken', 'Taro']};
    my $rule => [
        names => [
            'shift' # 'Ken'
        ]
    ];

Shift the head element of array.

trim

    my $data = {name => '  Ken  '};
    my $rule = [
        name => [
            'trim' # 'Ken'
        ]
    ];

Trim leading and trailing white space.

trim_collapse

    my $data = {name => '  Ken   Takagi  '};
    my $rule = [
        name => [
            'trim_collapse' # 'Ken Takagi'
        ]
    ];

Trim leading and trailing white space, and collapse all whitespace characters into a single space.

trim_lead

    my $data = {name => '  Ken  '};
    my $rule = [
        name => [
            'trim_lead' # 'Ken  '
        ]
    ];

Trim leading white space.

trim_trail

    my $data = {name => '  Ken  '};
    my $rule = [
        name => [
            'trim_trail' # '  Ken'
        ]
    ];

Trim trailing white space.

BUGS

Please tell me the bugs.

<kimoto.yuki at gmail.com>

STABILITY

Validator::Custom and Validator::Custom::Result is stable now. All methods in these documentations (except for experimantal marking ones) keep backword compatible in the future.

AUTHOR

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

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

COPYRIGHT & LICENCE

Copyright 2009 Yuki Kimoto, all rights reserved.

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