/ 
Declare-Constraints-Simple-0.03
River stage one • 1 direct dependent • 1 total dependent
/ Declare::Constraints::Simple

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