Declare::Constraints::Simple man page on Fedora

Man page or keyword search:  
man Server   31170 pages
apropos Keyword Search (all sections)
Output format
Fedora logo
[printable version]

Declare::Constraints::UserlContributed Perl DocDeclare::Constraints::Simple(3)

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.

perl v5.14.1			  2006-09-14   Declare::Constraints::Simple(3)
[top]

List of man pages available for Fedora

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net