NAME
    Validation::Class - Low-Fat Full-Flavored Data Modeling and Validation
    Framework

VERSION
    version 5.83

SYNOPSIS
        package MyVal::User;
    
        use Validation::Class;
    
        # rules mixin
    
        mxn basic       => {
            required    => 1,
            max_length  => 255,
            filters     => [qw/trim strip/]
        }; 
    
        # attr(s) w/rules
    
        fld id          => {
            mixin       => 'basic',
            max_length  => 11,
            required    => 0
        };
    
        fld name        => {
            mixin       => 'basic',
            min_length  => 2
        };
    
        fld email       => {
            mixin       => 'basic',
            min_length  => 3
        };
    
        fld login       => {
            mixin       => 'basic',
            min_length  => 5
        };
    
        fld password    => {
            mixin       => 'basic',
            min_length  => 5,
            min_symbols => 1
        };
    
        # just an attr
    
        has attitude => 1; 
    
        # self-validating method
    
        mth create  => {
    
            input   => [qw/name email login password/],
            output  => ['+id'],
        
            using   => sub {
            
                my ($self, @args) = @_;
            
                # make sure to set id for output validation
            
            }
    
        }; 
    
        package main;
    
        my $user = MyVal::User->new(name => '...', email => '...');
    
        unless ($user->create) {
    
            # did you forget your login and pass?
    
        }
    
        1;

    Validation::Class takes a different approach towards data validation, it
    centralizes data validation rules to ensure consistency through DRY
    (dont-repeat-yourself) code.

        use MyApp;
    
        my $params = {
           'user.login' => '...',
           'user.pass' => '...'
        };
    
        my $app = MyApp->new(params => $params);
    
        my $user = $app->class('user'); # instantiated MyApp::User object
    
        unless ($user->validate('login', 'pass')){
    
            # do something with ... $input->errors;
    
        }

DESCRIPTION
    Validation::Class is much more than a simple data validation framework,
    in-fact it is more of a data modeling framework and can be used as an
    alternative to minimalistic object systems such as Moo, Mo, etc.

    Validation::Class aims to provide the building blocks for easily
    definable self-validating data models.

    When fields (attributes with validation rules) are defined, accessors
    are automatically generated to make getting and setting their values
    much easier.

    Methods can be defined using the method keyword which can make the
    routine self-validating, checking the defined input requirements against
    existing validation rules before executing the routine gaining
    consistency and security.

KEYWORDS
  attribute
    The attribute keyword (or has) creates a class attribute.

        package MyApp::User;
    
        use Validate::Class;
    
        attribute 'attitude' => sub {
        
            return $self->bothered ? 1 : 0 
        
        };
    
        1;

    The attribute keyword takes two arguments, the attribute name and a
    constant or coderef that will be used as its default value.

  build
    The build keyword (or bld) registers a coderef to be run at
    instantiation much in the same way the common BUILD routine is used in
    modern-day OO systems.

        package MyApp::User;
    
        use Validation::Class;
    
        build sub {
        
            my $self = shift;
        
            # ... do something
        
        };

    The build keyword takes one argument, a coderef which is passed the
    instantiated class object.

  directive
    The directive keyword (or dir) creates custom validator directives to be
    used in your field definitions. It is a means of extending the
    pre-existing directives table before runtime and is ideal for creating
    custom directive extension packages to be used in all your classes.

        package MyApp::Directives;
    
        use Validation::Class;
        use Data::Validate::Email;
    
        directive 'is_email' => sub {
    
            my ($dir, $value, $field, $self) = @_;
        
            my $validator = Data::Validate::Email->new;
        
            unless ($validator->is_email($value)) {
        
                my $handle = $field->{label} || $field->{name};
                $self->error($field, "$handle must be a valid email address");
            
                return 0;
        
            }
        
            return 1;
    
        };
    
        package MyApp::User;
    
        use Validate::Class;
        use MyApp::Directives;
    
        field 'email' => {
            is_email => 1,
            ...
        };
    
        1;

    The directive keyword takes two arguments, the name of the directive and
    a coderef which will be used to validate the associated field. The
    coderef is passed four ordered parameters, the value of directive, the
    value of the field (parameter value), the field object (hashref), and
    the instantiated class object. The validator MUST return true or false.

  field
    The field keyword (or fld) creates an attribute with validation rules
    for reuse in code. The field keyword may also correspond with the
    parameter name expected to be passed to your validation class.

        package MyApp::User;
    
        use Validation::Class;
    
        field 'login' => {
            required   => 1,
            min_length => 1,
            max_length => 255,
            ...
        };

    The field keyword takes two arguments, the field name and a hashref of
    key/values pairs known as directives.

    Protip: Fields are used to validate constant and array data, not
    hashrefs and objects. Don't try to use fields like attributes (use the
    has keyword instead).

  filter
    The filter keyword (or flt) creates custom filters to be used in your
    field definitions. It is a means of extending the pre-existing filters
    table before runtime and is ideal for creating custom directive
    extension packages to be used in all your classes.

        package MyApp::Directives;
    
        use Validation::Class;
    
        filter 'flatten' => sub {
        
            $_[0] =~ s/[\t\r\n]+/ /g;
            $_[0] # return
    
        };
    
        package MyApp::User;
    
        use Validate::Class;
        use MyApp::Directives;
    
        field 'description' => {
            filters => ['trim', 'flatten'],
            ...
        };
    
        1;

    The filter keyword takes two arguments, the name of the filter and a
    coderef which will be used to filter the value the associated field. The
    coderef is passed the value of the field and that value MUST be operated
    on directly. The coderef should also return the transformed value.

  load
    The load keyword (or set), which can also be used as a method, provides
    options for extending the current class by attaching other
    Validation::Class classes as roles. The process of applying roles to the
    current class mainly involve copying the role's methods and
    configuration.

        package MyApp;
    
        use Validation::Class;
    
        # load specific child class
    
        load {
            ...
        };
    
        1;

    The "load.class" option, can be a constant or arrayref, will require
    other classes specifically and add them to the relationship map for
    convenient access through the class() method. Existing parameters and
    configuration options are passed to the child class' constructor. All
    attributes can be easily overwritten using the attribute's accessors on
    the child class.

        package MyApp;
    
        use Validation::Class;
    
        # load specific child class
    
        load {
            class => 'MyApp::Relative'
        };
    
        package main;
    
        my $app = MyApp->new;
    
        my $rel = $app->class('relative'); # instantiated MyApp::Relative object
        my $rel = $app->class('MyApp::Relative'); # alternatively
    
        1;

    The "load.classes" option, can be a constant or arrayref, uses
    Module::Find to load all child classes (in-all-subdirectories) for
    convenient access through the class() method. Existing parameters and
    configuration options are passed to the child class' constructor. All
    attributes can be easily overwritten using the attribute's accessors on
    the child class.

        package MyApp;
    
        use Validation::Class;
    
        # load specific child class
    
        load {
            classes => 1
        };
    
        package main;
    
        my $app = MyApp->new;
    
        my $rel = $app->class('relative'); # instantiated MyApp::Relative object
        my $rel = $app->class('MyApp::Relative'); # alternatively
    
        my $rel = $app->class('data_source'); # MyApp::DataSource
        my $rel = $app->class('data_source-first'); # MyApp::DataSource::First
    
        1;

    The "load.plugins" option is used to load plugins that support
    Validation::Class. A Validation::Class plugin is little more than a
    class that implements a "new" method that extends the associated
    validation class object. As usual, an official Validation::Class plugin
    can be referred to using shorthand while custom plugins are called by
    prefixing a plus symbol to the fully-qualified plugin name. Learn more
    about plugins at Validation::Class::Cookbook.

        package MyVal;
    
        load {
            plugins => [
                'CPANPlugin', # Validation::Class::Plugin::CPANPlugin
                '+MyVal::Plugin'
            ]
        };
    
        1;

    The "load.roles" option is used to load and inherit functionality from
    child classes, these classes should be used and thought-of as roles. Any
    validation class can be used as a role with this option.

        package MyVal::User;
    
        load {
            role => 'MyVal::Person'
        };
    
        # or
    
        load {
            roles => [
                'MyVal::Person'
            ]
        };
    
        1;

  method
    The method keyword (or mth) is used to create an auto-validating method.
    Similar to method signatures, an auto-validating method can leverage
    pre-existing validation rules and profiles to ensure a method has the
    required data necessary to proceed.

        package MyApp::User;
    
        use Validation::Class;
    
        method 'register' => {
    
            input  => ['name', '+email', 'login', '+password'],
            output => ['+id'], # optional output validation, dies on failure
            using  => sub {
        
                my ($self, @args) = @_;
            
                # .... do something registrationy
            
                $self->id(...); # set the ID field for output validation
            
                return $self;
        
            }
    
        };
    
        package main;
    
        my $user = MyApp::User->new(params => $params);
    
        if ($user->register) {
            ...
        }
    
        1;

    The method keyword takes two arguments, the name of the method to be
    created and a hashref of required key/value pairs. The hashref must have
    an "input" variable whose value is either an arrayref of fields to be
    validated, or a constant value which matches a validation profile name.
    The hashref must also have a "using" variable whose value is a coderef
    which will be executed upon successfully validating the input. Whether
    and what the method returns is yours to decide.

    Optionally the required hashref can have an "output" variable whose
    value is either an arrayref of fields to be validated, or a constant
    value which matches a validation profile name which will be used to
    perform data validation after the coderef has been executed. Please note
    that output validation failure will cause the program to die, the
    premise behind this decision is based on the assumption that given
    successfully validated input a routine's output should be predictable
    and if an error occurs it is most-likely a program error as opposed to a
    user error.

    See the ignore_failure and report_failure switch to control how method
    input validation failures are handled.

  mixin
    The mixin keyword (or mxn) creates a validation rules template that can
    be applied to any field using the mixin directive. Mixin directives are
    processed first so existing field directives will override the mixed-in
    directives.

        package MyApp::User;
    
        use Validation::Class;
    
        mixin 'constrain' => {
            required   => 1,
            min_length => 1,
            max_length => 255,
            ...
        };
    
        # e.g.
        field 'login' => {
            mixin => 'constrain',
            ...
        };

    The mixin keyword takes two arguments, the mixin name and a hashref of
    key/values pairs known as directives.

  profile
    The profile keyword (or pro) stores a validation profile (coderef) which
    as in the traditional use of the term is a sequence of validation
    routines that validate data relevant to a specific action.

        package MyApp::User;
    
        use Validation::Class;
    
        profile 'signup' => sub {
        
            my ($self, @args) = @_;
        
            return $self->validate(qw(
                +name
                +email
                +email_confirmation
                -login
                +password
                +password_confirmation
            ));
        
        };
    
        package main;
    
        my $user = MyApp::User->new(params => $params);
    
        unless ($user->validate_profile('signup')) {
    
            die $user->errors_to_string;
    
        }

    The profile keyword takes two arguments, a profile name and coderef
    which will be used to execute a sequence of actions for validation
    purposes.

METHODS
  new
    The new method, exported into the calling namespace automatically,
    should NOT be tampered with. The new method performs a series of actions
    (magic) required for the class to function properly. See the build
    keyword for hooking into the instantiation process.

        package MyApp;
    
        use Validation::Class;
    
        package main;
    
        my $app = MyApp->new;
    
        ...

ATTRIBUTES, METHODS, AND MORE
    This class encapsulates the functionality used to manipulate the
    environment of the calling class. The engine-class is the role that
    provides all of the data validation functionality, please see
    Validation::Class::Engine for more information on specific methods, and
    attributes.

  before
     before foo => sub { ... };

    See "before method(s) => sub { ... }" in Class::Method::Modifiers for
    full documentation.

  around
     around foo => sub { ... };

    See "around method(s) => sub { ... }" in Class::Method::Modifiers for
    full documentation.

  after
     after foo => sub { ... };

    See "after method(s) => sub { ... }" in Class::Method::Modifiers for
    full documentation.

AUTHOR
    Al Newkirk <awncorp@cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2011 by awncorp.

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

