Valiant::Validates - Role that adds class and instance methods supporting validations
See Valiant.
This is a role that adds class level validations to you Moo or Moose classes. The main point of entry for use and documentation currently is Valiant. Here we have API level documentation without details or examples. You should read Valiant first and then you can refer to documentation her for further details.
In addition to methods this class provides, it also proves all methods from Valiant::Translation
Used to declare validations on an attribute. The first argument is either a scalar or arrayref of scalars which should be attributes on your object:
__PACKAGE__->validates( name => (...) ); __PACKAGE__->validates( ['name', 'age'] => (...));
Following arguments should be in one of three forms: a coderef or subroutine reference that contains validation rules, a key - value pair which is a validator class and its arguments or lastly you can pass in a Type::Tiny constraint directly. You may also have key value pairs which are global arguments for the validate set as a whole:
package Local::Model::User; use Moo; use Valiant::Validations; # Importer that wraps Valiant::Validates use Types::Standard 'Int'; has ['name', 'age'] => (is=>'ro); validates name => ( length => { minimum => 5, maximum => 25 }, format => { match => 'words' }, sub { my ($self, $attribute, $value, $opts) = @_; $self->errors->add($attribute, "can't be Joe. We hate Joe :)" ,$opts) if $value eq 'Joe'; }, +{ arg1=>'1', arg2=>2 }, # args are optional for coderefs but are passed into $opts \&must_be_unique, ); validates age => ( Int->where('$_ >= 65'), +{ message => 'A retiree must be at least 65 years old, }, ..., # additional validations ); sub must_be_unique { my ($self, $attribute, $value, $opts) = @_; # Some local validation to make sure the name is unique in storage (like a database). }
If you use a validator class name then the hashref of arguments that follows is not optional. If you pass an options hashref it should contain arguments that are defined for the validation type you are passing or one of the global arguments: on, message, if and unless. See "GLOBAL OPTIONS" for more.
on
message
if
unless
For subroutine reference and Type::Tiny objects you can or not pass an options hashref depending on your needs. Additionally the three types can be mixed and matched within a single validates clause.
validates
When you use a validator class (such as length = { minimum => 5, maximum => 25 }>) we resolve the class name length in the following way. We first camel case the name and then look for a 'Validator' package in the current class namespace. If we don't find a match we check each namespace up the hierarchy and then check the two global namespaces Valiant::ValidatorX and Validate::Validator. For example if you declare validators as in the example class above Local::Model::User we would look for the following:
length =
length
Valiant::ValidatorX
Validate::Validator
Local::Model::User
Local::Model::User::Validator::Length Local::Model:::Validator::Length Local::Validator::Length Validator::Length Valiant::ValidatorX::Length Valiant::Validator::Length
These get checked in the order above and loaded and instantiated once at setup time.
NOTE: The namespace Valiant::Validator is reserved for validators that ship with Valiant. The Valiant::ValidatorX namespace is reserved for additional validators on CPAN that are packaged separately from Valiant. If you wish to share a custom validator that you wrote the proper namespace to use on CPAN is Valiant::ValidatorX.
Valiant::Validator
You can also prepend your validator name with '+' which will cause Valiant to ignore the namespace resolution and try to load the class directly. For example:
validates_with '+App::MyValidator';
Will try to load the class App::MyValidator and use it as a validator directly (or throw an exception if it fails to load).
App::MyValidator
validates_with is intended to process validations that are on the class as a whole, or which are very complex and can't easily be assigned to a single attribute. It accepts either a subroutine reference with an optional hash of key value pair options (which are passed to $opts) or a scalar name which should be a stand alone validator class (basically a class that does the validates method although you should consume the Validate::Validator role to enforce the contract).
validates_with
$opts
__PACKAGE__->validates_with(sub { my ($self, $opts) = @_; ... }); __PACKAGE__->validates_with(\&check_object => (arg1=>'foo', arg2=>'bar')); sub check_object { my ($self, $opts) = @_; ... } __PACKAGE__->validates with('Custom' => (arg1=>'foo', arg2=>'bar'));
If you pass a string that is a validator class we resolve its namespace using the same approach as detailed above for validates. Any arguments are passed to the new method of the found class excluding global options.
new
Run validation rules on the current object, optionally with arguments hash. If validation has already been run on this object, we clear existing errors and run validations again. Currently the return value of this method is not defined in the API. Example:
$object->validate(%args);
Currently the only arguments with defined meaning is context, which is used to defined a validation context. All other arguments will be passed down to the $opts hashref.
context
Return true or false depending on if the current object state is valid or not. If you call this method and validations have not been run (via validate) then we will first run validations and pass any arguments to "validates". If validations have already been run we just return true or false directly UNLESS you pass arguments in which case we clear errors first and then rerun validations with the arguments before returning true or false.
validate
Returns a boolean indicating if the object currently has errors. This does not run a validation check first (unlike valid or invalid). So if you just want to check the current state of the errors list and not tamper with that state you can use this.
valid
invalid
Clears any errors and sets the object as though validations hd never been run.
Sets skip_validation to true and returns $self
skip_validation
$self
Sets skip_validation to false and returns $self
Set a validation context (or arrayref of contexts) that will be used on an following validations.ß
An instance of Valiant::Errors.
This attribute will be true if validations have already been been run on the current instance. It merely says if validations have been run or not, it does not indicate if validations have been passed or failed see "valid" pr "invalid"
When true do not run validations, even if you call ->validate
John Napiorkowski email:jjnapiork@cpan.org
Valiant::Validations
Copyright 2020, John Napiorkowski email:jjnapiork@cpan.org
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
1 POD Error
The following errors were encountered while parsing the POD:
Non-ASCII character seen before =encoding in 'validations.ß'. Assuming UTF-8
To install Valiant, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Valiant
CPAN shell
perl -MCPAN -e shell install Valiant
For more information on module installation, please visit the detailed CPAN module installation guide.