/ 
Syccess-0.104
River stage one • 2 direct dependents • 2 total dependents
/ Syccess

NAME

Syccess - Easy Validation Handler

VERSION

version 0.104

SYNOPSIS

use Syccess;

my $syccess = Syccess->new(
  fields => [
    foo => [ required => 1, length => 4, label => 'PIN Code' ],
    bar => [ required => { message => 'You have 5 seconds to comply.' } ],
    # if no label is given its made out of the name so 'Bar' in this case
    baz => [ length => { min => 2, max => 4 }, label => 'Ramba Zamba' ],
  ],
);

my $result = $syccess->validate( foo => 1, bar => 1 );
if ($result->success) {
  print "Yeah!\n";
}

my $failed = $syccess->validate();
unless ($failed->success) {
  for my $message (@{$failed->errors}) {
    print $message->message."\n";
  }
}

my $traitsful_syccess = Syccess->new(
  result_traits => [qw( MyApp::Syccess::ResultRole )],
  error_traits => [qw( MyApp::Syccess::ErrorRole )],
  field_traits => [qw( MyApp::Syccess::FieldRole )],
  fields => [
    # ...
  ],
);

DESCRIPTION

Syccess is developed for SyContent.

Syccess is a simple validation layer, which allows to check a hash of values against a validation definition and give back success or allow to see the error messages of the failure. Syccess is not made for caring about anything else, so for a higher level library you integrate Syccess and not try to extend it. Syccess is not made for giving extra attributes to the fields, the validator should be the key topic here, and it is very easy to make own validators specific for your environment, see Syccess::Validator and Syccess::ValidatorSimple, but you should be aware that most requirements should be covered with Syccess::Validator::Code and Syccess::Validator::Call, as both allow you to use simple validation methods you already may have in your model. This way you don't end up making Syccess specific procedures, that might be harder to maintain.

The complete concept of Syccess is read only, which means, a call to "validate" will produce a Syccess::Result which contains the resulting information, while the Syccess object stays unchanged. A Syccess object contains a Syccess::Field object for every field of your "fields" definition. On this field you have an object for every validator. Be aware that the validators are given as ArrayRef and you can use the same validator several times.

BEHAVIOUR INFO: The validators provided by the Syccess core are all designed to ignore a non existing value, an undefined value or an empty string. If you want that giving those leads to an error, then you must use the required validator of Syccess::Validator::Required. If you need to check against those values, for example you use Syccess::Validator::Code and in some cases an undefined value is valid and sometimes not, then you must make a custom validator, see "custom_validator_namespaces".

ATTRIBUTES

fields

Required ArrayRef containing the definition of the fields for the validation. It always first the name of the field and then an ArrayRef again with the validators. Those will be dispatched to instantiation Syccess::Field to create the fields objects. See more about validators on its attribute at Syccess::Field. You can provide a validator several times, like several regex or several code validators.

validator_namespaces

This attribute is the main namespace collection, where Syccess searches for its validators. Normally you do not set it directly, instead you set "custom_validator_namespaces", else you would remove Syccess::Validator and the SyccessX::Validator, which are automatically added after the "custom_validator_namespaces" by default here.

custom_validator_namespaces

Here you define an ArrayRef of the namespaces that should be used additional to the default ones. For example, if you add validator foo_bar, then Syccess would search first with your custom namespace, for example MyApp::Validator::FooBar, and after that it checks for Syccess::Validator::FooBar and finally SyccessX::Validator::FooBar.

For making custom validator, you must use the Syccess::Validator role, which allows to check over all params given. If you just want to make a simple validator that checks against only the relevant value of the field, then you can use Syccess::ValidatorSimple.

Please use SyccessX::Validator as namespace if you want to upload a new general validator to CPAN.

result_class

The class which is used for the result. Default is Syccess::Result.

error_class

The class which is used for errors. Default is Syccess::Error.

field_class

The class which is used for the fields. Default is Syccess::Field.

result_traits

Traits to be added to the Syccess::Result class. See with_traits at MooX::Traits.

error_traits

Traits to be added to the Syccess::Error class. See with_traits at MooX::Traits.

field_traits

Traits to be added to the Syccess::Field class. See with_traits at MooX::Traits.

errors_args

Here you can give custom attributes which are dispatched to the instantiation of the "error_class" objects.

METHODS

new_with_traits

See MooX::Traits.

field

Get the Syccess::Field for the name given as parameter.

fields

Get all Syccess::Field of the Syccess object.

validate

This is the main function to produce a "result_class" object, which will then hold the result and the errors of the validation process. This function must be called with a Hash (no HashRef yet supported) of the values to check for the validation.

Core Validators

call

Syccess::Validator::Call - Calling a method on an object for validation

code

Syccess::Validator::Code - Using a CodeRef to validate

in

Syccess::Validator::In - Checking if a value is in a given list of values

is_number

Syccess::Validator::IsNumber - Check if the value is a number

length

Syccess::Validator::Length - Check for length of the string, if its specific or min or max values.

regex

Syccess::Validator::Regex - Check the value against a regex

required

Syccess::Validator::Required - Value must be provided, and cant be empty

Label Concept

The system is designed to deliver a validation only, which leaded to the decision to not include the ability to give fields specific attributes. As a consequence out of this, the implementation of a label concept (so a visual representation of the field name in the error message) is done with a special trick, as seen in the "SYNOPSIS", through giving it as just another validator, it will then be consumed as label for the field instead of the load of another validator object.

TODO

One bigger feature planned is adding the ability to stack Syccess objects to allow cascaded parameters for validation. Currently this is not implemented, because, if you integrate Syccess in a bigger context, you will want to control the cascading yourself (in my case SyForm takes the control of this). But I hope I will find later the time to make this possible.

SUPPORT

IRC

Join irc.perl.org and msg Getty

Repository

http://github.com/Getty/p5-syccess
Pull request and additional contributors are welcome

Issue Tracker

http://github.com/Getty/p5-syccess/issues

AUTHOR

Torsten Raudssus <torsten@raudss.us>

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by Torsten Raudssus.

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