NAME
Data::DynamicValidator - JPointer-like and Perl union for flexible perl data structures validation
VERSION
version 0.02
SYNOPSIS
my $my_complex_config = {
features => [
"a/f",
"application/feature1",
"application/feature2",
],
service_points => {
localhost => {
"a/f" => { job_slots => 3, },
"application/feature1" => { job_slots => 5 },
"application/feature2" => { job_slots => 5 },
},
"127.0.0.1" => {
"application/feature2" => { job_slots => 5 },
},
},
mojolicious => {
hypnotoad => {
pid_file => '/tmp/hypnotoad-ng.pid',
listen => [ 'http://localhost:3000' ],
},
},
};
use Data::DynamicValidator qw/validator/;
use Net::hostent;
my $errors = validator($cfg)->(
on => '/features/*',
should => sub { @_ > 0 },
because => "at least one feature should be defined",
each => sub {
my $f = $_->();
shift->(
on => "/service_points/*/`$f`/job_slots",
should => sub { defined($_[0]) && $_[0] > 0 },
because => "at least 1 service point should be defined for feature '$f'",
)
}
)->(
on => '/service_points/sp:*',
should => sub { @_ > 0 },
because => "at least one service point should be defined",
each => sub {
my $sp;
shift->report_error("SP '$sp' isn't resolvable")
unless gethost($sp);
}
)->(
on => '/service_points/sp:*/f:*',
should => sub { @_ > 0 },
because => "at least one feature under service point should be defined",
each => sub {
my ($sp, $f);
shift->(
on => "/features/`*[value eq '$f']`",
should => sub { 1 },
because => "Feature '$f' of service point '$sp' should be decrlared in top-level features list",
)
},
)->(
on => '/mojolicious/hypnotoad/pid_file',
should => sub { @_ == 1 },
because => "hypnotoad pid_file should be defined",
)->(
on => '/mojolicious/hypnotoad/listen/*',
should => sub { @_ > 0 },
because => "hypnotoad listening interfaces defined",
)->errors;
print "all OK\n"
unless(@$errors);DESCRIPTION
First of all, you should create Validator instance:
use Data::DynamicValidator qw/validator/;
my $data = { ports => [2222] };
my $v = validator($data);Then, actually do validation:
$v->(
on => '/ports/*',
should => sub { @_ > 0 },
because => 'At least one port should be defined at "ports" section',
);The on parameter defines the data path, via JSON-pointer like expression; the should parameter provides the closure, which will check the values gathered on via pointer. If the closure returns false, then the error will be recorded, with description, provided by because parameter.
To get the results of validation, you can call:
$v->is_valid; # returns true, if there is no validation errors
$v->errors; # returns array reference, consisting of the met Errorson/should parameters are convenient for validation of presense of something, but they aren't so handy in checking of individual values. To handle that the optional each pareter has been introduced.
my $data = { ports => [2222, 3333] };
$v->(
on => '/ports/*',
should => sub { @_ > 0 },
because => 'At least one port should be defined at "ports" section',
each => sub {
my $port = $_->();
$v->report_error("All ports should be greater than 1000")
unless $port > 1000;
},
);So, report_error could be used for custom errors reporting on current path or current data value. The $_ is the an implicit alias or label to the last componenet of the current path, i.e. on our case the current path in each closure will be /ports/0 and /ports/1, so the $_ will be 0 and 1 respectively. To get the value of the label, you should "invoke" it, as showed previously. A label stringizes to the last data path component, e.g. to "0" and "1" respectively.
The each closure single argrument is the validator instance itself. The previous example could be rewriten with explicit label like:
$v->(
on => '/ports/port:*',
should => sub { @_ > 0 },
because => 'At least one port should be defined at "ports" section',
each => sub {
my $port;
my $port_value = $port->();
shift->report_error("All ports should be greater than 1000")
unless $port_value > 1000;
},
);Providing aliases for array indices may be not so handy as for keys of hashes. Please note, that the label port was previously "declated" in on rule, and only then "injected" into $port variable in each closure.
Consider the following example:
my $data = {
ports => [2000, 3000],
2000 => 'tcp',
3000 => 'udp',
};Let's validate it. The validation rule sounds as: there is 'ports' section, where at least one port > 1000 should be declated, and then the same port should appear at top-level, and it should either 'tcp' or 'upd' type.
use List::MoreUtils qw/any/;
my $errors = validator($data)->(
on => '/ports/*[value > 1000 ]',
should => sub { @_ > 0 },
because => 'At least one port > 1000 should be defined in "ports" section',
each => sub {
my $port = $_->();
shift->(
on => "/*[key eq $port]",
should => sub { @_ == 1 && any { $_[0] eq $_ } (qw/tcp udp/) },
because => "The port $port should be declated at top-level as tcp or udp",
)
}
)->errors;METHODS
validate
Performs validation based on 'on', 'should', 'because' and optional 'each' parameters. Returns the validator itself ($self), to allow further 'chain' invocations. The validation will not be performed, if some errors already have been detected.
It is recommended to use overloaded function call, instead of this method call. (e.g. $validator->(...) instead of $validato->validate(...);
report_error
The method is used for custom errors reporing. It is mainly usable in 'each' closure.
validator({ ports => [1000, 2000, 3000] })->(
on => '/ports/port:*',
should => sub { @_ > 0 },
because => "At least one listening port should be defined",
each => sub {
my $port;
my $port_value = $port->();
shift->report_error("Port value $port_value isn't acceptable, because < 1000")
if($port_value < 1000);
}
);is_valid
Checks, weather validator already has errors
errors
Returns internal array of errors
FUNCTIONS
validator
The enter point for DynamicValidator.
my $errors = validator(...)->(
on => "...",
should => sub { ... },
because => "...",
)->errors;RATIONALE
There are complex data configurations, e.g. application configs. Not to check them on applicaiton startup is wrong, because of sudden unexpected runtime errors can occur, which not-so-pleasent to detect. Write the code, that does full exhaustive checks, is boring.
This module offers to use DLS, that makes data validation funny yet understandable for the person, which provides the data.
DATA PATH EXPRESSIONS
my $data = [qw/a b c d e/];
'/2' # selects the 'c' value in $data array
'/-1' # selects the 'e' value in $data array
$data = { abc => 123 };
'/abc' # selects the '123' value in hashref under key 'abc'
$data = {
mojolicious => {
hypnotoad => {
pid_file => '/tmp/hypnotoad-ng.pid',
}
}
};
'/mojolicious/hypnotoad/pid_file' # point to pid_file
# Escaping by back-quotes sample
$data => { "a/b" => { c => 5 } }
'/`a/b`/c' # selects 5
$data = {abc => [qw/a b/]}; # 1
$data = {abc => { c => 'd'}}; # 2
$data = {abc => 7}; # 3
'/abc/*' # selects 'a' and 'b' in 1st case
# the 'd' in 2nd case
# the number 7 in 3rd case
# Filtering capabilities samples:
'/abc/*[size == 5]' # filter array/hash by size
'/abc/*[value eq "z"]' # filter array/hash by value equality
'/abc/*[index > 5]' # finter array by index
'/abc/*[key =~ /def/]' # finter hash by keyDEBUGGING
You can set the DATA_DYNAMICVALIDATOR_DEBUG environment variable to get some advanced diagnostics information printed to "STDERR".
DATA_DYNAMICVALIDATOR_DEBUG=1RESOURCES
Data::DPath
AUTHOR
Ivan Baidakou <dmol@gmx.com>
COPYRIGHT AND LICENSE
This software is copyright (c) 2014 by Ivan Baidakou.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.