1Data::Constraint(3)   User Contributed Perl Documentation  Data::Constraint(3)
2
3
4

NAME

6       Data::Constraint - prototypical value checking
7

SYNOPSIS

9               use Data::Constraint;
10
11               my $constraint = Data::Constraint->add_constraint(
12                       'name_of_condition',
13                       run         => sub { $_[1] =~ /Perl/ },
14                       description => "String should have 'Perl' in it";
15                       );
16
17               if( $constraint->check( 'Java' ) )
18                       {
19                       ...
20                       }
21

DESCRIPTION

23       A constraint is some sort of condition on a datum.  This module checks
24       one condition against one value at a time, and I call the thing that
25       checks that condition the "constraint".  A constraint returns true or
26       false, and that's it.  It should have no side effects, it should not
27       change program flow, and it should mind its own business. Let the thing
28       that calls the constraint figure out what to do with it. I want
29       something that says "yes" or "no" (and I discuss why this needs a fancy
30       module later).
31
32       For instance, the constraint may state that the value has to be a
33       number.  The condition may be something that ensures the value does not
34       have non-digits.
35
36               $value =~ /^\d+\z/
37
38       The value may have additional constraints, such as a lower limit.
39
40               $value > $minimum
41
42       Although I designed constraints to be a single condition, you may want
43       to create contraints that check more than one thing.
44
45               $value > $minimum and $value < $maximum
46
47       In the previous examples, we could tell what was wrong with the value
48       if the return value was false: the value didn't satisfy it's single
49       condition.  If it was supposed to be all digits and wasn't, then it had
50       non-digits.  If it was supposed to be greater than the minimum value,
51       but wasn't, it was less than (or equal to) the minimal value.  With
52       more than one condition, like the last example, I cannot tell which one
53       failed. I might be able to say that a value of out of range, but I
54       think it is nicer to know if the value should have been larger or
55       smaller so I can pass that on to the user.  Having said that, I give
56       you enough rope to do what you wish.
57
58   Why I need a fancy, high-falutin' module
59       This module is a sub-class of "Class::Prototyped".  In brief, that
60       means constraints are class-objects even if they don't look like they
61       are.  Each constraint is a self-contained class, and I can modify a
62       constraint by adding data and behaviour without affecting any of the
63       other constraints.  I can also make a list of constraints that I store
64       for later use (also known as "delayed" execution).
65
66       Several data may need the same conditions, so they can share the same
67       constraint.  Other data that need different constraints can get their
68       own, or modify copies of ones that exist.
69
70       I can also associate several constraints with some data, and each one
71       has its own constraint.  In the compelling case for this module, I
72       needed to generate different warnings for different failures.
73
74   Interacting with a constraint
75       I can get a constraint object by asking for it.
76
77               my $constraint = Data::Constraint->get_by_name( $name );
78
79       If no constraint has that name, I get back the default constraint which
80       always returns true. Or should it be false?  I guess that depends on
81       what you are doing.
82
83       If I don't know which constraints exist, I can get all the names. The
84       names are just simple strings, so they have no magic.  Maybe this
85       should be a hash so you can immediately use the value of the key you
86       want.
87
88               my @names = Data::Constraint->get_all_names;
89
90       Once I have the constraint, I give it a value to check if
91
92               $constraint->check( $value );
93
94       I can do this all in one step.
95
96               Data::Constraint->get_by_name( $name )->check( $value );
97
98   Predefined constraints
99       I previously had some pre-loaded contraints ("defined", "ordinal", and
100       "test") but that got in the way of things that didn't want them.  You
101       can still find them defined in the test files though.
102
103   Adding a new constraint
104       Add a new constraint with the class method "add_constraint". The first
105       argument is the name you want to give the constraint.  The rest of the
106       arguments are optional, although I need to add a "run" key if I want
107       the constraint to do anything useful: its value should be something
108       that returns true when the value satisfies the condition (so a constant
109       is probably not what you want).  An anonymous subroutine is probably
110       what you want.
111
112               Data::Constraint->add_constraint(
113                       $name_of_constraint,
114                       'run' => sub {...},
115                       [ @optional_arguments ],
116                       );
117
118       Once I create the constraint, it exists forever (for now).  I get back
119       the constraint object:
120
121               my $constraint = Data::Constraint->add_constraint( ... );
122
123       The object sticks around after $constraint goes out of scope.  The
124       $constraint is just a reference to the object.  I can get another
125       reference to it through get_by_name().  See "Deleting a constraint" if
126       you want to get rid of them.
127
128   Modifying a constraint
129       Um, don't do that yet unless you know what you are doing.
130
131   Deleting a constraint
132               Data::Constraint->delete_by_name( $name );
133
134               Data::Constraint->delete_all();
135
136   Doing anything you want
137       You wish!  This module can't help you there.
138

METHODS

140       check( VALUE )
141           Apply the constraint to the VALUE.
142
143       add_constraint( NAME, KEY-VALUES )
144           Added a constraint with name NAME. Possible keys and values:
145
146                   run            reference to subroutine to run
147                   description    string that decribes the constraint
148
149           Example:
150
151                   Data::Constraint->add_constraint(
152                           $name_of_constraint,
153                           'run'       => sub {...},
154                           description => 'This is what I do",
155                           );
156
157       get_all_names
158           Return a list of all the defined constraints.
159
160       get_by_name( CONSTRAINT_NAME )
161           Return the constraint with name CONSTRAINT_NAME. This is
162
163       delete_by_name( CONSTRAINT_NAME )
164           Delete the constraint with name CONSTRAINT_NAME. It's no longer
165           available.
166
167       delete_all()
168           Delete all the constraints, even the default ones.
169
170       description
171           Return the description. The default description is the empty
172           string. You should supply your own description with
173           "add_constraint".
174
175       run Return the description. The default description is the empty
176           string. You should supply your own description with
177           "add_constraint".
178

SOURCE AVAILABILITY

180       This source is in Github:
181
182               https://github.com/briandfoy/data-constraint
183

AUTHOR

185       brian d foy, "<bdfoy@cpan.org>"
186
188       Copyright © 2004-2022, brian d foy <bdfoy@cpan.org>. All rights
189       reserved.
190
191       This program is free software; you can redistribute it and/or modify it
192       under the terms of the Artistic License 2.0.
193
194
195
196perl v5.38.0                      2023-07-20               Data::Constraint(3)
Impressum