/ 
Oogly-0.02-withoutworldwriteables
/ Oogly

NAME

Oogly - Oogly - A Data validation idea that just might be ideal!

VERSION

version 0.02

SYNOPSIS

Oogly is a different approach to data validation, it attempts to simplify and centralize data validation rules to ensure DRY (don't repeat yourself) code. PLEASE NOTE! It is not the intent of this module to provide validation routines but instead to provide simplistic validation flow-control, and promote code reuse. The following is an example of that...

use MyApp::Validation;
my $app = MyApp::Validation->new(\%params);
if ($app->validate('login', 'password')){
    ...
}

package MyApp::Validation
use Oogly;

# define a mixin, a sortof template that can be included with other rules
# by using the mixin directive
mixin 'default' => {
    required    => 1,
    min_length  => 4,
    max_length  => 255
};

# define a data validation rule for parameter `login` using the default
# mixin where the `login` must be between 4-255 characters long and have
# at least one letter and number
field 'login' => {
    label => 'user login',
    mixin => 'default',
    validation => sub {
        my ($self, $this, $params) = @_;
        my ($name, $value) = ($this->{name}, $this->{value});
        $self->error($this, "field $name must contain at least one letter and number")
            if ($value !~ /[a-zA-Z]/ && $value !~ /[0-9]/);
    }
};

# define a data validation rule for parameter `password` using the
# previously defined field `login` as the mixin (template)
field 'password' => {
    mixin_field => 'login',
    label => 'user password'
};

METHODS

new

The new method instantiates a new Oogly or Oogly package instance.

field

The field function defines the validation rules for the specified parameter it is named after. e.g. field 'some_data' => {...}, validates against the value of the hash reference where the key is `some_data`.

field 'some_param' => {
    mixin => 'default',
    validation => sub {
        my ($v, $this, $params) = @_;
        $v->error($this, "...")
            if ...
    }
};

Fields are comprised of specific directives, those directives are as follows:
name: The name of the field (auto set)
value: The value of the parameter matching the name of the field (auto set)
mixin: The template to be used to copy directives from

mixin 'template' => {
    required => 1
};

field 'a_field' => {
    mixin => 'template'
}

mixin_field: The field to be used as a mixin(template) to copy directives from

field 'a_field' => {
    required => 1,
    min_length => 2,
    max_length => 10
};

field 'b_field' => {
    mixin_field => 'a_field'
};

validation: A validation routine that returns true or false

field '...' => {
    validation => sub {
        my ($self, $field, $all_parameters) = @_;
        return 1
    }
};

errors: The collection of errors encountered during processing (auto set arrayref)
label: An alias for the field name, something more human-readable
error: A custom error message, displayed instead of the generic ones
required : Determines whether the field is required or not, takes 1/0 true of false
min_length: Determines the maximum length of characters allowed
max_length: Determines the minimum length of characters allowed
ref_type: Determines whether the field value is a valid perl reference variable
regex: Determines whether the field value passed the regular expression test

field 'c_field' => {
    label => 'a field labeled c',
    error => 'a field labeled c cannot ',
    required => 1,
    min_length => 2,
    max_length => 25,
    ref_type => 'array',
    regex => '^\d+$'
};

mixin

The mixin function defines validation rule templates to be later reused by more specifically defined fields.

mixin 'default' => {
    required    => 1,
    min_length  => 4,
    max_length  => 255
};

error

The error function is used to set and/or retrieve errors encountered or set during validation. The error function with no parameters returns the error message arrayref which can be used to output a single concatenated error message a with delimeter.

$self->error() # returns an array of errors
join '<br/>', $self->error(); # html-break delimeted errors
$self->error('some_param'); # show parameter-specific error messages arrayref
$self->error($this, "$name must conform ..."); # set error, see `field` function

errors

The errors function is a synonym for the error function.

check_mixin

The check_mixin function is used internally to validate the defined keys and values of mixins.

check_field

The check_field function is used internally to validate the defined keys and values of fields.

use_mixin

The use_mixin function sequentially applies defined mixin parameteres (as templates)to the specified field.

use_mixin_field

The use_mixin_field function copies the properties (directives) of a specified field to the target field processing copied mixins along the way.

validate

The validate function sequentially checks the passed-in field names against their defined validation rules and returns undef or 1.

basic_validate

The basic_validate function processes the pre-defined contraints e.g., required, min_length, max_length, etc.

AUTHOR

Al Newkirk <awncorp@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2010 by Al Newkirk.

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