1Data::Constraint(3) User Contributed Perl Documentation Data::Constraint(3)
2
6 Data::Constraint - prototypical value checking
7
9 use Data::Constraint;
10 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 if( $constraint->check( 'Java' ) )
18 {
19 ...
20 }
21
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 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 $value =~ /^\d+\z/
37 The value may have additional constraints, such as a lower limit.
39 $value > $minimum
41 Although I designed constraints to be a single condition, you may want
43 to create contraints that check more than one thing.
44 $value > $minimum and $value < $maximum
46 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 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 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 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 Interacting with a constraint
75 I can get a constraint object by asking for it.
76 my $constraint = Data::Constraint->get_by_name( $name );
78 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 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 my @names = Data::Constraint->get_all_names;
89 Once I have the constraint, I give it a value to check if
91 $constraint->check( $value );
93 I can do this all in one step.
95 Data::Constraint->get_by_name( $name )->check( $value );
97 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 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 Data::Constraint->add_constraint(
113 $name_of_constraint,
114 'run' => sub {...},
115 [ @optional_arguments ],
116 );
117 Once I create the constraint, it exists forever (for now). I get back
119 the constraint object:
120 my $constraint = Data::Constraint->add_constraint( ... );
122 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 Modifying a constraint
129 Um, don't do that yet unless you know what you are doing.
130 Deleting a constraint
132 Data::Constraint->delete_by_name( $name );
133 Data::Constraint->delete_all();
135 Doing anything you want
137 You wish! This module can't help you there.
138
140 check( VALUE )
141 Apply the constraint to the VALUE.
142 add_constraint( NAME, KEY-VALUES )
144 Added a constraint with name NAME. Possible keys and values:
145 run reference to subroutine to run
147 description string that decribes the constraint
148 Example:
150 Data::Constraint->add_constraint(
152 $name_of_constraint,
153 'run' => sub {...},
154 description => 'This is what I do",
155 );
156 get_all_names
158 Return a list of all the defined constraints.
159 get_by_name( CONSTRAINT_NAME )
161 Return the constraint with name CONSTRAINT_NAME. This is
162 delete_by_name( CONSTRAINT_NAME )
164 Delete the constraint with name CONSTRAINT_NAME. It's no longer
165 available.
166 delete_all()
168 Delete all the constraints, even the default ones.
169 description
171 Return the description. The default description is the empty
172 string. You should supply your own description with
173 "add_constraint".
174 run Return the description. The default description is the empty
176 string. You should supply your own description with
177 "add_constraint".
178
180 This source is in Github:
181 https://github.com/briandfoy/data-constraint
183
185 brian d foy, "<bdfoy@cpan.org>"
186
188 Copyright © 2004-2022, brian d foy <bdfoy@cpan.org>. All rights
189 reserved.
190 This program is free software; you can redistribute it and/or modify it
192 under the terms of the Artistic License 2.0.
193perl v5.38.0 2023-07-20 Data::Constraint(3)