NAME

       Declare::Constraints::Simple - Declarative Validation of Data Structures

SYNOPSIS

         use Declare::Constraints::Simple-All;

         my $profile = IsHashRef(
                           -keys   => HasLength,
                           -values => IsArrayRef( IsObject ));

         my $result1 = $profile->(undef);
         print $result1->message, "\n";    # 'Not a HashRef'

         my $result2 = $profile->({foo => [23]});

         print $result2->message, "\n";    # 'Not an Object'

         print $result2->path, "\n";
                           # 'IsHashRef[val foo].IsArrayRef[0].IsObject'

DESCRIPTION

       The main purpose of this module is to provide an easy way to build a profile to validate a
       data structure. It does this by giving you a set of declarative keywords in the importing
       namespace.

USAGE

       This is just a brief intro. For details read the documents mentioned in "SEE ALSO".

   Constraint Import
         use Declare::Constraints::Simple-All;

       The above command imports all constraint generators in the library into the current
       namespace. If you want only a selection, use "only":

         use Declare::Constraints::Simple
             Only => qw(IsInt Matches And);

       You can find all constraints (and constraint-like generators, like operators. In fact,
       "And" above is an operator. They're both implemented equally, so the distinction is a
       merely philosophical one) documented in the Declare::Constraints::Simple::Library pod. In
       that document you will also find the exact parameters for their usage, so this here is
       just a brief Intro and not a coverage of all possibilities.

   Building a Profile
       You can use these constraints by building a tree that describes what data structure you
       expect. Every constraint can be used as sub-constraint, as parent, if it accepts other
       constraints, or stand-alone. If you'd just say

         my $check = IsInt;
         print "yes!\n" if $check->(23);

       it will work too. This also allows predefining tree segments, and nesting them:

         my $id_to_objects = IsArrayRef(IsObject);

       Here $id_to_objects would give it's OK on an array reference containing a list of objects.
       But what if we now decide that we actually want a hashref containing two lists of objects?
       Behold:

         my $object_lists =
           IsHashRef( HasAllKeys( qw(good bad) ),
                      OnHashKeys( good => $id_to_objects,
                                  bad  => $id_to_objects ));

       As you can see, constraints like "IsArrayRef" and "IsHashRef" allow you to apply
       constraints to their keys and values. With this, you can step down in the data structure.

   Applying a Profile to a Data Structure
       Constraints return just code references that can be applied to one value (and only one
       value) like this:

         my $result = $object_lists->($value);

       After this call $result contains a Declare::Constraints::Simple::Result object. The first
       think one wants to know is if the validation succeeded:

         if ($result->is_valid) { ... }

       This is pretty straight forward. To shorten things the result object also overloads it's
       "bool"ean context. This means you can alternatively just say

         if ($result) { ... }

       However, if the result indicates a invalid data structure, we have a few options to find
       out what went wrong. There's a human parsable message in the "message" accessor. You can
       override these by forcing it to a message in a subtree with the "Message" declaration. The
       "stack" contains the name of the chain of constraints up to the point of failure.

       You can use the "path" accessor for a joined string path representing the stack.

   Creating your own Libraries
       You can declare a package as a library with

         use Declare::Constraints::Simple-Library;

       which will install the base class and helper methods to define constraints. For a complete
       list read the documentation in Declare::Constraints::Simple::Library::Base. You can use
       other libraries as base classes to include their constraints in your export possibilities.
       This means that with a package setup like

         package MyLibrary;
         use warnings;
         use strict;

         use Declare::Constraints::Simple-Library;
         use base 'Declare::Constraints::Simple::Library';

         constraint 'MyConstraint',
           sub { return _result(($_[0] >= 12), 'Value too small') };

         1;

       you can do

         use MyLibrary-All;

       and have all constraints, from the default library and yours from above, installed into
       your requesting namespace. You can override a constraint just by redeclaring it in a
       subclass.

   Scoping
       Sometimes you want to validate parts of a data structure depending on another part of it.
       As of version 2.0 you can declare scopes and store results in them. Here is a complete
       example:

         my $constraint =
           Scope('foo',
             And(
               HasAllKeys( qw(cmd data) ),
               OnHashKeys(
                 cmd => Or( SetResult('foo', 'cmd_a',
                              IsEq('FOO_A')),
                            SetResult('foo', 'cmd_b',
                              IsEq('FOO_B')) ),
                 data => Or( And( IsValid('foo', 'cmd_a'),
                                  IsArrayRef( IsInt )),
                             And( IsValid('foo', 'cmd_b'),
                                  IsRegex )) )));

       This profile would accept a hash references with the keys "cmd" and "data". If "cmd" is
       set to "FOO_A", then "data" has to be an array ref of integers. But if "cmd" is set to
       "FOO_B", a regular expression is expected.

SEE ALSO

       Declare::Constraints::Simple::Library, Declare::Constraints::Simple::Result,
       Declare::Constraints::Simple::Base, Module::Install

REQUIRES

       Carp::Clan, aliased, Class::Inspector, Scalar::Util, overload and Test::More (for build).

TODO

       •   Examples.

       •   A list of questions that might come up, together with their answers.

       •   A "Custom" constraint that takes a code reference.

       •   Create stack objects that stringify to the current form, but can hold more data.

       •   Give the "Message" constraint the ability to get the generated constraint inserted in
           the message. A possibility would be to replace __Value__ and __Message__. It might
           also accept code references, which return strings.

       •   Allow the "IsCodeRef" constraint to accept further constraints. One might like to
           check, for example, the refaddr of a closure.

       •   A "Captures" constraint that takes a regex and can apply other constraints to the
           matches.

       •   ???

       •   Profit.

INSTALLATION

         perl Makefile.PL
         make
         make test
         make install

       For details read Module::Install.

AUTHOR

       Robert 'phaylon' Sedlacek "<phaylon@dunkelheit.at>"

LICENSE AND COPYRIGHT

       This module is free software, you can redistribute it and/or modify it under the same
       terms as perl itself.