From 475181f3ea5e4525c76d84303d66de99eafbfccb Mon Sep 17 00:00:00 2001 From: Jesse Luehrs Date: Tue, 9 Oct 2012 23:19:32 -0500 Subject: docs --- lib/MooseX/Meta/TypeConstraint/Doctype.pm | 36 +++++++++++++ lib/MooseX/Validation/Doctypes.pm | 88 +++++++++++++++++++++++++++++++ lib/MooseX/Validation/Doctypes/Errors.pm | 63 ++++++++++++++++++++++ 3 files changed, 187 insertions(+) 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 function in L. It is a subclass of +L which adds a required C 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 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, or browse to +L. + +=head1 SEE ALSO + +L + +L + +=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 + +=item * CPAN Ratings + +L + +=item * RT: CPAN's request tracker + +L + +=item * Search CPAN + +L + +=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 and +C 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', -- cgit v1.2.3