Debian Codegraph @

README

raw
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