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 providing you with
   a set of declarative keywords exported into your namespace.

USAGE
     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.

   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.

   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.

METHODS
 import($flag, @args)
   Exports the constraints to the calling namespace.

 _build_handle_map()
   Internal method to build constraint-to-class mappings.

 _export_all($target, $handle_map)
   Internal method. Exports all handles in $handle_map into the $target
   namespace.

 _export_these($target, $handle_map, @constraints)
   Internal method. Exports all @constraints from $handle_map into the
   $target namespace.

SEE ALSO
   Declare::Constraints::Simple::Library,
   Declare::Constraints::Simple::Result

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

TODO
   *   More tests of course!

   *   An "OnArrayElements" constraint. Like "OnHashKeys" but for array
       references.

   *   Examples.

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

   *   Inheritance. Developers should be able to make their own libraries
       and define own constraints.

   *   Dependencies. We need keywords like "As($name, $constraint" and
       "IfValid($name, $constraint)".

   *   Scoping. It would be nice to have a "Let" constraint that introduces
       variables. These could be set under their scope with a "SetValue"
       constraint and retrieved with "GetValue". This would open the
       possibility of comparison operators.

   *   ???

   *   Profit.

AUTHOR
   Robert 'phaylon' Sedlacek "<[email protected]>"

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

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.