Declare::Constraints::Simple(3pm)

1Declare::Constraints::SUismeprleC(o3n)tributed Perl DocuDmeecnltaartei:o:nConstraints::Simple(3)
2
3
4

NAME

6       Declare::Constraints::Simple - Declarative Validation of Data Struc‐
7       tures
8

SYNOPSIS

10         use Declare::Constraints::Simple-All;
11
12         my $profile = IsHashRef(
13                           -keys   => HasLength,
14                           -values => IsArrayRef( IsObject ));
15
16         my $result1 = $profile->(undef);
17         print $result1->message, "\n";    # 'Not a HashRef'
18
19         my $result2 = $profile->({foo => [23]});
20
21         print $result2->message, "\n";    # 'Not an Object'
22
23         print $result2->path, "\n";
24                           # 'IsHashRef[val foo].IsArrayRef[0].IsObject'
25

DESCRIPTION

27       The main purpose of this module is to provide an easy way to build a
28       profile to validate a data structure. It does this by giving you a set
29       of declarative keywords in the importing namespace.
30

USAGE

32       This is just a brief intro. For details read the documents mentioned in
33       "SEE ALSO".
34
35       Constraint Import
36
37         use Declare::Constraints::Simple-All;
38
39       The above command imports all constraint generators in the library into
40       the current namespace. If you want only a selection, use "only":
41
42         use Declare::Constraints::Simple
43             Only => qw(IsInt Matches And);
44
45       You can find all constraints (and constraint-like generators, like
46       operators. In fact, "And" above is an operator. They're both imple‐
47       mented equally, so the distinction is a merely philosophical one) docu‐
48       mented in the Declare::Constraints::Simple::Library pod. In that docu‐
49       ment you will also find the exact parameters for their usage, so this
50       here is just a brief Intro and not a coverage of all possibilities.
51
52       Building a Profile
53
54       You can use these constraints by building a tree that describes what
55       data structure you expect. Every constraint can be used as sub-con‐
56       straint, as parent, if it accepts other constraints, or stand-alone. If
57       you'd just say
58
59         my $check = IsInt;
60         print "yes!\n" if $check->(23);
61
62       it will work too. This also allows predefining tree segments, and nest‐
63       ing them:
64
65         my $id_to_objects = IsArrayRef(IsObject);
66
67       Here $id_to_objects would give it's OK on an array reference containing
68       a list of objects. But what if we now decide that we actually want a
69       hashref containing two lists of objects? Behold:
70
71         my $object_lists =
72           IsHashRef( HasAllKeys( qw(good bad) ),
73                      OnHashKeys( good => $id_to_objects,
74                                  bad  => $id_to_objects ));
75
76       As you can see, constraints like "IsArrayRef" and "IsHashRef" allow you
77       to apply constraints to their keys and values. With this, you can step
78       down in the data structure.
79
80       Applying a Profile to a Data Structure
81
82       Constraints return just code references that can be applied to one
83       value (and only one value) like this:
84
85         my $result = $object_lists->($value);
86
87       After this call $result contains a Declare::Constraints::Simple::Result
88       object. The first think one wants to know is if the validation suc‐
89       ceeded:
90
91         if ($result->is_valid) { ... }
92
93       This is pretty straight forward. To shorten things the result object
94       also overloads it's "bool"ean context. This means you can alternatively
95       just say
96
97         if ($result) { ... }
98
99       However, if the result indicates a invalid data structure, we have a
100       few options to find out what went wrong. There's a human parsable mes‐
101       sage in the "message" accessor. You can override these by forcing it to
102       a message in a subtree with the "Message" declaration. The "stack" con‐
103       tains the name of the chain of constraints up to the point of failure.
104
105       You can use the "path" accessor for a joined string path representing
106       the stack.
107
108       Creating your own Libraries
109
110       You can declare a package as a library with
111
112         use Declare::Constraints::Simple-Library;
113
114       which will install the base class and helper methods to define con‐
115       straints. For a complete list read the documentation in Declare::Con‐
116       straints::Simple::Library::Base. You can use other libraries as base
117       classes to include their constraints in your export possibilities. This
118       means that with a package setup like
119
120         package MyLibrary;
121         use warnings;
122         use strict;
123
124         use Declare::Constraints::Simple-Library;
125         use base 'Declare::Constraints::Simple::Library';
126
127         constraint 'MyConstraint',
128           sub { return _result(($_[0] >= 12), 'Value too small') };
129
130         1;
131
132       you can do
133
134         use MyLibrary-All;
135
136       and have all constraints, from the default library and yours from
137       above, installed into your requesting namespace. You can override a
138       constraint just by redeclaring it in a subclass.
139
140       Scoping
141
142       Sometimes you want to validate parts of a data structure depending on
143       another part of it. As of version 2.0 you can declare scopes and store
144       results in them. Here is a complete example:
145
146         my $constraint =
147           Scope('foo',
148             And(
149               HasAllKeys( qw(cmd data) ),
150               OnHashKeys(
151                 cmd => Or( SetResult('foo', 'cmd_a',
152                              IsEq('FOO_A')),
153                            SetResult('foo', 'cmd_b',
154                              IsEq('FOO_B')) ),
155                 data => Or( And( IsValid('foo', 'cmd_a'),
156                                  IsArrayRef( IsInt )),
157                             And( IsValid('foo', 'cmd_b'),
158                                  IsRegex )) )));
159
160       This profile would accept a hash references with the keys "cmd" and
161       "data". If "cmd" is set to "FOO_A", then "data" has to be an array ref
162       of integers. But if "cmd" is set to "FOO_B", a regular expression is
163       expected.
164

REQUIRES

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

TODO

174       ·   Examples.
175
176       ·   A list of questions that might come up, together with their
177           answers.
178
179       ·   A "Custom" constraint that takes a code reference.
180
181       ·   Create stack objects that stringify to the current form, but can
182           hold more data.
183
184       ·   Give the "Message" constraint the ability to get the generated con‐
185           straint inserted in the message. A possibility would be to replace
186           __Value__ and __Message__. It might also accept code references,
187           which return strings.
188
189       ·   Allow the "IsCodeRef" constraint to accept further constraints. One
190           might like to check, for example, the refaddr of a closure.
191
192       ·   A "Captures" constraint that takes a regex and can apply other con‐
193           straints to the matches.
194
195       ·   ???
196
197       ·   Profit.
198

INSTALLATION

200         perl Makefile.PL
201         make
202         make test
203         make install
204
205       For details read Module::Install.
206

AUTHOR

208       Robert 'phaylon' Sedlacek "<phaylon@dunkelheit.at>"
209

LICENSE AND COPYRIGHT

211       This module is free software, you can redistribute it and/or modify it
212       under the same terms as perl itself.
213
214
215
216perl v5.8.8                       2006-09-11   Declare::Constraints::Simple(3)