| 1 |
NAME |
| 2 |
Declare::Constraints::Simple - Declarative Validation of Data Structures |
| 3 |
|
| 4 |
SYNOPSIS |
| 5 |
use Declare::Constraints::Simple-All; |
| 6 |
|
| 7 |
my $profile = IsHashRef( |
| 8 |
-keys => HasLength, |
| 9 |
-values => IsArrayRef( IsObject )); |
| 10 |
|
| 11 |
my $result1 = $profile->(undef); |
| 12 |
print $result1->message, "\n"; # 'Not a HashRef' |
| 13 |
|
| 14 |
my $result2 = $profile->({foo => [23]}); |
| 15 |
|
| 16 |
print $result2->message, "\n"; # 'Not an Object' |
| 17 |
|
| 18 |
print $result2->path, "\n"; |
| 19 |
# 'IsHashRef[val foo].IsArrayRef[0].IsObject' |
| 20 |
|
| 21 |
DESCRIPTION |
| 22 |
The main purpose of this module is to provide an easy way to build a |
| 23 |
profile to validate a data structure. It does this by giving you a set |
| 24 |
of declarative keywords in the importing namespace. |
| 25 |
|
| 26 |
USAGE |
| 27 |
This is just a brief intro. For details read the documents mentioned in |
| 28 |
"SEE ALSO". |
| 29 |
|
| 30 |
Constraint Import |
| 31 |
use Declare::Constraints::Simple-All; |
| 32 |
|
| 33 |
The above command imports all constraint generators in the library into |
| 34 |
the current namespace. If you want only a selection, use "only": |
| 35 |
|
| 36 |
use Declare::Constraints::Simple |
| 37 |
Only => qw(IsInt Matches And); |
| 38 |
|
| 39 |
You can find all constraints (and constraint-like generators, like |
| 40 |
operators. In fact, "And" above is an operator. They're both implemented |
| 41 |
equally, so the distinction is a merely philosophical one) documented in |
| 42 |
the Declare::Constraints::Simple::Library pod. In that document you will |
| 43 |
also find the exact parameters for their usage, so this here is just a |
| 44 |
brief Intro and not a coverage of all possibilities. |
| 45 |
|
| 46 |
Building a Profile |
| 47 |
You can use these constraints by building a tree that describes what |
| 48 |
data structure you expect. Every constraint can be used as |
| 49 |
sub-constraint, as parent, if it accepts other constraints, or |
| 50 |
stand-alone. If you'd just say |
| 51 |
|
| 52 |
my $check = IsInt; |
| 53 |
print "yes!\n" if $check->(23); |
| 54 |
|
| 55 |
it will work too. This also allows predefining tree segments, and |
| 56 |
nesting them: |
| 57 |
|
| 58 |
my $id_to_objects = IsArrayRef(IsObject); |
| 59 |
|
| 60 |
Here $id_to_objects would give it's OK on an array reference containing |
| 61 |
a list of objects. But what if we now decide that we actually want a |
| 62 |
hashref containing two lists of objects? Behold: |
| 63 |
|
| 64 |
my $object_lists = |
| 65 |
IsHashRef( HasAllKeys( qw(good bad) ), |
| 66 |
OnHashKeys( good => $id_to_objects, |
| 67 |
bad => $id_to_objects )); |
| 68 |
|
| 69 |
As you can see, constraints like "IsArrayRef" and "IsHashRef" allow you |
| 70 |
to apply constraints to their keys and values. With this, you can step |
| 71 |
down in the data structure. |
| 72 |
|
| 73 |
Applying a Profile to a Data Structure |
| 74 |
Constraints return just code references that can be applied to one value |
| 75 |
(and only one value) like this: |
| 76 |
|
| 77 |
my $result = $object_lists->($value); |
| 78 |
|
| 79 |
After this call $result contains a Declare::Constraints::Simple::Result |
| 80 |
object. The first think one wants to know is if the validation |
| 81 |
succeeded: |
| 82 |
|
| 83 |
if ($result->is_valid) { ... } |
| 84 |
|
| 85 |
This is pretty straight forward. To shorten things the result object |
| 86 |
also overloads it's "bool"ean context. This means you can alternatively |
| 87 |
just say |
| 88 |
|
| 89 |
if ($result) { ... } |
| 90 |
|
| 91 |
However, if the result indicates a invalid data structure, we have a few |
| 92 |
options to find out what went wrong. There's a human parsable message in |
| 93 |
the "message" accessor. You can override these by forcing it to a |
| 94 |
message in a subtree with the "Message" declaration. The "stack" |
| 95 |
contains the name of the chain of constraints up to the point of |
| 96 |
failure. |
| 97 |
|
| 98 |
You can use the "path" accessor for a joined string path representing |
| 99 |
the stack. |
| 100 |
|
| 101 |
Creating your own Libraries |
| 102 |
You can declare a package as a library with |
| 103 |
|
| 104 |
use Declare::Constraints::Simple-Library; |
| 105 |
|
| 106 |
which will install the base class and helper methods to define |
| 107 |
constraints. For a complete list read the documentation in |
| 108 |
Declare::Constraints::Simple::Library::Base. You can use other libraries |
| 109 |
as base classes to include their constraints in your export |
| 110 |
possibilities. This means that with a package setup like |
| 111 |
|
| 112 |
package MyLibrary; |
| 113 |
use warnings; |
| 114 |
use strict; |
| 115 |
|
| 116 |
use Declare::Constraints::Simple-Library; |
| 117 |
use base 'Declare::Constraints::Simple::Library'; |
| 118 |
|
| 119 |
constraint 'MyConstraint', |
| 120 |
sub { return _result(($_[0] >= 12), 'Value too small') }; |
| 121 |
|
| 122 |
1; |
| 123 |
|
| 124 |
you can do |
| 125 |
|
| 126 |
use MyLibrary-All; |
| 127 |
|
| 128 |
and have all constraints, from the default library and yours from above, |
| 129 |
installed into your requesting namespace. You can override a constraint |
| 130 |
just by redeclaring it in a subclass. |
| 131 |
|
| 132 |
Scoping |
| 133 |
Sometimes you want to validate parts of a data structure depending on |
| 134 |
another part of it. As of version 2.0 you can declare scopes and store |
| 135 |
results in them. Here is a complete example: |
| 136 |
|
| 137 |
my $constraint = |
| 138 |
Scope('foo', |
| 139 |
And( |
| 140 |
HasAllKeys( qw(cmd data) ), |
| 141 |
OnHashKeys( |
| 142 |
cmd => Or( SetResult('foo', 'cmd_a', |
| 143 |
IsEq('FOO_A')), |
| 144 |
SetResult('foo', 'cmd_b', |
| 145 |
IsEq('FOO_B')) ), |
| 146 |
data => Or( And( IsValid('foo', 'cmd_a'), |
| 147 |
IsArrayRef( IsInt )), |
| 148 |
And( IsValid('foo', 'cmd_b'), |
| 149 |
IsRegex )) ))); |
| 150 |
|
| 151 |
This profile would accept a hash references with the keys "cmd" and |
| 152 |
"data". If "cmd" is set to "FOO_A", then "data" has to be an array ref |
| 153 |
of integers. But if "cmd" is set to "FOO_B", a regular expression is |
| 154 |
expected. |
| 155 |
|
| 156 |
SEE ALSO |
| 157 |
Declare::Constraints::Simple::Library, |
| 158 |
Declare::Constraints::Simple::Result, |
| 159 |
Declare::Constraints::Simple::Base, Module::Install |
| 160 |
|
| 161 |
REQUIRES |
| 162 |
Carp::Clan, aliased, Class::Inspector, Scalar::Util, overload and |
| 163 |
Test::More (for build). |
| 164 |
|
| 165 |
TODO |
| 166 |
* Examples. |
| 167 |
|
| 168 |
* A list of questions that might come up, together with their answers. |
| 169 |
|
| 170 |
* A "Custom" constraint that takes a code reference. |
| 171 |
|
| 172 |
* Create stack objects that stringify to the current form, but can |
| 173 |
hold more data. |
| 174 |
|
| 175 |
* Give the "Message" constraint the ability to get the generated |
| 176 |
constraint inserted in the message. A possibility would be to |
| 177 |
replace __Value__ and __Message__. It might also accept code |
| 178 |
references, which return strings. |
| 179 |
|
| 180 |
* Allow the "IsCodeRef" constraint to accept further constraints. One |
| 181 |
might like to check, for example, the refaddr of a closure. |
| 182 |
|
| 183 |
* A "Captures" constraint that takes a regex and can apply other |
| 184 |
constraints to the matches. |
| 185 |
|
| 186 |
* ??? |
| 187 |
|
| 188 |
* Profit. |
| 189 |
|
| 190 |
INSTALLATION |
| 191 |
perl Makefile.PL |
| 192 |
make |
| 193 |
make test |
| 194 |
make install |
| 195 |
|
| 196 |
For details read Module::Install. |
| 197 |
|
| 198 |
AUTHOR |
| 199 |
Robert 'phaylon' Sedlacek "<[email protected]>" |
| 200 |
|
| 201 |
LICENSE AND COPYRIGHT |
| 202 |
This module is free software, you can redistribute it and/or modify it |
| 203 |
under the same terms as perl itself. |
| 204 |
|