GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  DECLARE::CONSTRAINTS::SIMPLE (3)

.ds Aq ’

NAME

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

CONTENTS

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

o Examples.
o A list of questions that might come up, together with their answers.
o A Custom constraint that takes a code reference.
o Create stack objects that stringify to the current form, but can hold more data.
o 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.
o Allow the IsCodeRef constraint to accept further constraints. One might like to check, for example, the refaddr of a closure.
o A Captures constraint that takes a regex and can apply other constraints to the matches.
o ???
o 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.
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 DECLARE::CONSTRAINTS::SIMPLE (3) 2006-09-14

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.