summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJesse Luehrs <doy@tozt.net>2012-10-09 23:19:32 -0500
committerJesse Luehrs <doy@tozt.net>2012-10-09 23:19:32 -0500
commit475181f3ea5e4525c76d84303d66de99eafbfccb (patch)
treed55bc7773aefb97b30555b1db8fdc9bff5d36b04
parentbb2bf61723962222952d2f68da497f8391dc6a5e (diff)
downloadmoosex-validation-doctypes-475181f3ea5e4525c76d84303d66de99eafbfccb.tar.gz
moosex-validation-doctypes-475181f3ea5e4525c76d84303d66de99eafbfccb.zip
docs
-rw-r--r--lib/MooseX/Meta/TypeConstraint/Doctype.pm36
-rw-r--r--lib/MooseX/Validation/Doctypes.pm88
-rw-r--r--lib/MooseX/Validation/Doctypes/Errors.pm63
3 files changed, 187 insertions, 0 deletions
diff --git a/lib/MooseX/Meta/TypeConstraint/Doctype.pm b/lib/MooseX/Meta/TypeConstraint/Doctype.pm
index 0d333cc..9502424 100644
--- a/lib/MooseX/Meta/TypeConstraint/Doctype.pm
+++ b/lib/MooseX/Meta/TypeConstraint/Doctype.pm
@@ -1,5 +1,6 @@
package MooseX::Meta::TypeConstraint::Doctype;
use Moose;
+# ABSTRACT: Moose type constraint for validating doctypes
use Devel::PartialDump 'dump';
use Moose::Util::TypeConstraints qw(class_type find_type_constraint
@@ -8,10 +9,45 @@ use Scalar::Util 'weaken';
use MooseX::Validation::Doctypes::Errors;
+=head1 SYNOPSIS
+
+ use MooseX::Validation::Doctypes;
+
+ doctype 'Person' => {
+ id => 'Str',
+ name => 'Str',
+ title => 'Str',
+ };
+
+ use JSON;
+
+ my $data = decode_json('{"id": "1234-A", "name": "Bob", "title": "CIO"}');
+
+ use Moose::Util::TypeConstraints;
+
+ my $person = find_type_constraint('Person');
+ die "Data is invalid" unless $person->check($data);
+
+=head1 DESCRIPTION
+
+This module implements the actual type constraint that is created by the
+C<doctype> function in L<MooseX::Validation::Doctypes>. It is a subclass of
+L<Moose::Meta::TypeConstraint> which adds a required C<doctype> parameter, and
+automatically generates a constraint and message which validate based on that
+doctype (as described in the MooseX::Validation::Doctypes docs).
+
+=cut
+
extends 'Moose::Meta::TypeConstraint';
class_type('Moose::Meta::TypeConstraint');
+=attr doctype
+
+The doctype to validate. Required.
+
+=cut
+
has doctype => (
is => 'ro',
isa => 'Ref',
diff --git a/lib/MooseX/Validation/Doctypes.pm b/lib/MooseX/Validation/Doctypes.pm
index 668c4f0..c29e125 100644
--- a/lib/MooseX/Validation/Doctypes.pm
+++ b/lib/MooseX/Validation/Doctypes.pm
@@ -1,6 +1,7 @@
package MooseX::Validation::Doctypes;
use strict;
use warnings;
+# ABSTRACT: validation of nested data structures with Moose type constraints
use MooseX::Meta::TypeConstraint::Doctype;
@@ -11,6 +12,49 @@ use Sub::Exporter -setup => {
},
};
+=head1 SYNOPSIS
+
+ use MooseX::Validation::Doctypes;
+
+ doctype 'Person' => {
+ id => 'Str',
+ name => 'Str',
+ title => 'Str',
+ };
+
+ use JSON;
+
+ my $data = decode_json('{"id": "1234-A", "name": "Bob", "title": "CIO"}');
+
+ use Moose::Util::TypeConstraints;
+
+ my $person = find_type_constraint('Person');
+ my $errors = $person->validate($data);
+
+ use Data::Dumper;
+
+ warn Dumper($errors->errors) if $errors->has_errors;
+ warn Dumper($errors->extra_data) if $errors->has_extra_data;
+
+=head1 DESCRIPTION
+
+This module allows you to declare L<Moose> type constraints to validate nested
+data structures as you may get back from a JSON web service or something along
+those lines. The doctype declaration can be any arbitrarily nested structure of
+hashrefs and arrayrefs, and will be used to validate a data structure which has
+that same form. The leaf values in the doctype should be Moose type
+constraints, which will be used to validate the leaf nodes in the given data
+structure.
+
+=cut
+
+=func doctype $name, $doctype
+
+Declares a new doctype type constraint. C<$name> is optional, and if it is not
+given, an anonymous type constraint is created instead.
+
+=cut
+
sub doctype {
my $name;
$name = shift if @_ > 1;
@@ -32,4 +76,48 @@ sub doctype {
return $tc;
}
+=head1 BUGS
+
+No known bugs.
+
+Please report any bugs through RT: email
+C<bug-moosex-validation-doctypes at rt.cpan.org>, or browse to
+L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=MooseX-Validation-Doctypes>.
+
+=head1 SEE ALSO
+
+L<Moose::Meta::TypeConstraint>
+
+L<MooseX::Types::Structured>
+
+=head1 SUPPORT
+
+You can find this documentation for this module with the perldoc command.
+
+ perldoc MooseX::Validation::Doctypes
+
+You can also look for information at:
+
+=over 4
+
+=item * AnnoCPAN: Annotated CPAN documentation
+
+L<http://annocpan.org/dist/MooseX-Validation-Doctypes>
+
+=item * CPAN Ratings
+
+L<http://cpanratings.perl.org/d/MooseX-Validation-Doctypes>
+
+=item * RT: CPAN's request tracker
+
+L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=MooseX-Validation-Doctypes>
+
+=item * Search CPAN
+
+L<http://search.cpan.org/dist/MooseX-Validation-Doctypes>
+
+=back
+
+=cut
+
1;
diff --git a/lib/MooseX/Validation/Doctypes/Errors.pm b/lib/MooseX/Validation/Doctypes/Errors.pm
index d510670..7ca640e 100644
--- a/lib/MooseX/Validation/Doctypes/Errors.pm
+++ b/lib/MooseX/Validation/Doctypes/Errors.pm
@@ -1,11 +1,74 @@
package MooseX::Validation::Doctypes::Errors;
use Moose;
+# ABSTRACT: error class for MooseX::Validation::Doctypes
+
+=head1 SYNOPSIS
+
+ use MooseX::Validation::Doctypes;
+
+ doctype 'Person' => {
+ id => 'Str',
+ name => 'Str',
+ title => 'Str',
+ };
+
+ use JSON;
+
+ my $data = decode_json('{"id": "1234-A", "name": "Bob", "title": "CIO"}');
+
+ use Moose::Util::TypeConstraints;
+
+ my $person = find_type_constraint('Person');
+ my $errors = $person->validate($data);
+
+ use Data::Dumper;
+
+ warn Dumper($errors->errors) if $errors->has_errors;
+ warn Dumper($errors->extra_data) if $errors->has_extra_data;
+
+=head1 DESCRIPTION
+
+This class holds the errors that were found when validating a doctype. There
+are two types of errors: either an existing piece of data didn't validate
+against the given type constraint, or extra data was provided that wasn't
+listed in the doctype. These two types correspond to the C<errors> and
+C<extra_data> attributes described below.
+
+=cut
+
+=attr errors
+
+Returns the errors that were detected. The return value will be a data
+structure with the same form as the doctype, except only leaves corresponding
+to values that failed to match their corresponding type constraint. The values
+will be an appropriate error message.
+
+=method has_errors
+
+Returns true if any errors were found when validating the data against the type
+constraints.
+
+=cut
has errors => (
is => 'ro',
predicate => 'has_errors',
);
+=attr extra_data
+
+Returns the extra data that was detected. The return value will be a data
+structure with the same form as the incoming data, except only containing
+leaves for data which was not represented in the doctype. The values will be
+the values from the actual data being validated.
+
+=method has_extra_data
+
+Returns true if any extra data was found when comparing the data to the
+doctype.
+
+=cut
+
has extra_data => (
is => 'ro',
predicate => 'has_extra_data',