Simple/Library/Base.pm

filter: Statementstmt 100% 106 / 106 Branchbran 87.5% 14 / 16 Conditioncond 75.0% 6 / 8 MC/DCmcdc 0.0% 0 / 4 Subroutinesub 100% 29 / 29 Podpod 100% 6 / 6 totaltotal 95.2% 161 / 169 CC 14 SCAR 7.4
CC
14
Cov
97%
_apply_checks
5.0
_result
4.0
__ANON__
3.0
CRAP 2.1
« Simple/Library/Operators.pm ↑ Summary Simple/Library/Numerical.pm »
1 =head1 NAME
2  
3 Declare::Constraints::Simple::Library::Base - Library Base Class
4  
5 =cut
6  
7 package Declare::Constraints::Simple::Library::Base;
8 14 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
9 14 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
10  
11 14 ▶use aliased 'Declare::Constraints::Simple::Result';
Subroutine BEGIN: called CC=1 SCAR=0.0
12  
13 14 ▶use Carp::Clan qw(^Declare::Constraints::Simple);
Subroutine BEGIN: called CC=1 SCAR=0.0
14  
15 14 our $FAIL_MESSAGE_DEFAULT = 'Validation Error';
16 14 our $FAIL_MESSAGE = '';
17 14 our $FAIL_INFO;
18 14 our %SCOPES;
19  
20 14 ▶use base 'Declare::Constraints::Simple::Library::Exportable';
Subroutine BEGIN: called CC=1 SCAR=0.0
21  
22 =head1 SYNOPSIS
23  
24 package My::Constraint::Library;
25 use warnings;
26 use strict;
27  
28 # this installs the base class and helper functions
29 use Declare::Constraints::Simple-Library;
30  
31 # we can also automagically provide other libraries
32 # to the importer
33 use base 'Declare::Constraints::Simple::Library::Numericals';
34  
35 # with this we define a constraint to check a value
36 # against a serial number regular expression
37 constraint 'SomeSerial',
38 sub {
39 return sub {
40 return _true if $_[0] =~ /\d{3}-\d{3}-\d{4}/;
41 return _false('Not in SomeSerial format');
42 };
43 };
44
45 1;
46  
47 =head1 DESCRIPTION
48  
49 This base class contains the common library functionalities. This
50 includes helper functions and install mechanisms.
51  
52 =head1 METHODS
53  
54 =head2 install_into($target)
55  
56 Installs the base classes and helper functions into the C<$target>
57 namespace. The C<%CONSTRAINT_GENERATORS> package variable of that class
58 will be used as storage for it's constraints.
59  
60 =cut
61  
62 106 ▶sub install_into {
Subroutine install_into: called CC=2 SCAR=6.9
Pod documented
63 106 my ($class, $target) = @_;
64  
65 14 ▶ { no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
66 106 unshift @{$target . '::ISA'}, $class;
67  
68 1272 *{$target . '::' . $_} = $class->can($_)
69 106 for qw/
70 constraint
71 _apply_checks
72 _listify
73 _result
74 _false
75 _true
76 _info
77 _with_message
78 _with_scope
79 _set_result
80 _get_result
81 _has_result
82 /;
83 }
84  
85 106 1;
86 }
87  
88 =head2 fetch_constraint_declarations()
89  
90 Class method. Returns all constraints registered to the class.
91  
92 =cut
93  
94 153 ▶sub fetch_constraint_declarations {
Subroutine fetch_constraint_declarations: called CC=1 SCAR=0.0
Pod documented
95 153 my ($class) = @_;
96
97 14 ▶ { no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
98 14 ▶ no warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
99 153 return keys %{$class . '::CONSTRAINT_GENERATORS'};
100 }
101 }
102  
103 =head2 fetch_constraint_generator($name)
104  
105 Class method. Returns the constraint generator code reference registered
106 under C<$name>. The call will raise a C<croak> if the generator could not
107 be found.
108  
109 =cut
110  
111 220 ▶sub fetch_constraint_generator {
Subroutine fetch_constraint_generator: called CC=2 SCAR=6.9
Pod documented
112 220 my ($class, $name) = @_;
113  
114 220 my $generator = do {
115 14 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
116 220 ${$class . '::CONSTRAINT_GENERATORS'}{$name};
117 };
118 220 ▶ croak "Unknown Constraint Generators: $name"
Branch: 1 branch
BranchTrueFalseTotal
unless $generator 0 220 220
119 unless $generator;
120  
121 220 return $class->prepare_generator($name, $generator);
122 }
123  
124 =head2 prepare_generator($constraint_name, $generator)
125  
126 Class method. This wraps the C<$generator> in a closure that provides
127 stack and failure-collapsing decisions.
128  
129 =cut
130  
131 220 ▶sub prepare_generator {
Subroutine prepare_generator: called CC=1 SCAR=0.0
Pod documented
132 220 my ($class, $constraint, $generator) = @_;
133 356 ▶ return sub {
Subroutine __ANON__: called CC=1 SCAR=0.0
134 356 my (@g_args) = @_;
135 356 my $closure = $generator->(@g_args);
136  
137 573 ▶ return sub {
Subroutine __ANON__: called CC=3 SCAR=11.0
138 573 my (@c_args) = @_;
139  
140 573 local $FAIL_INFO;
141 573 my $result = $closure->(@c_args);
142 573 my $info = '';
143 573 ▶ if ($FAIL_INFO) {
Branch: 1 branch
BranchTrueFalseTotal
if ($Declare::Constraints::Simple::Library::Base::FAIL_INFO) 85 488 573
144 85 $info = $FAIL_INFO;
145 85 $info =~ s/([\[\]])/\\$1/gsm;
146 85 $info = "[$info]";
147 }
148 573 ▶ $result->add_to_stack($constraint . $info) unless $result;
Branch: 1 branch
BranchTrueFalseTotal
unless $result 238 335 573
149  
150 573 return $result;
151 354 };
152 220 };
153 }
154  
155 =head2 add_constraint_generator($name, $code)
156  
157 Class method. The actual registration method, used by C<constraint>.
158  
159 =cut
160  
161 459 ▶sub add_constraint_generator {
Subroutine add_constraint_generator: called CC=1 SCAR=0.0
Pod documented
162 459 my ($class, $name, $code) = @_;
163  
164 14 ▶ { no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
165 459 ${$class . '::CONSTRAINT_GENERATORS'}{$name} = $code;
166 }
167  
168 459 1;
169 }
170  
171 =head1 HELPER FUNCTIONS
172  
173 Note that some of the helper functions are prefixed with C<_>. Although
174 this means they are internal functions, it is ok to call them, as they
175 have a fixed API. They are not distribution internal, but library
176 internal, and only intended to be used from inside constraints.
177  
178 =head2 constraint($name, $code)
179  
180 constraint 'Foo', sub { ... };
181  
182 This registers a new constraint in the calling library. Note that
183 constraints B<have to> return result objects. To do this, you can use the
184 helper functions L<_result($bool, $msg>, L<_true()> and L<_false($msg)>.
185  
186 =cut
187  
188 459 ▶sub constraint {
Subroutine constraint: called CC=1 SCAR=0.0
Pod documented
189 459 my ($name, $code) = @_;
190 459 my $target = scalar(caller);
191 459 $target->add_constraint_generator($name => $code);
192  
193 459 1;
194 }
195  
196 =head2 _result($bool, $msg)
197  
198 Returns a new result object. It's validity flag will depend on the
199 C<$bool> argument. The C<$msg> argument is the error message to use on
200 failure.
201  
202 =cut
203  
204 605 ▶sub _result {
Subroutine _result: called CC=4 SCAR=13.9
205 605 my ($result, $msg) = @_;
206 605 my $result_obj = Result->new;
207 605 $result_obj->set_valid($result);
208 605 ▶ $result_obj->set_message(
Branch: 1 branch
BranchTrueFalseTotal
unless $result_obj->is_valid 159 446 605
Condition83%5/6
$Declare::Constraints::Simple::Library::Base::FAIL_MESSAGE || $msg || $Declare::Constraints::Simple::Library::Base::FAIL_MESSAGE_DEFAULT
l!l&&r!l&&!r
15810
$Declare::Constraints::Simple::Library::Base::FAIL_MESSAGE or $msg
l!l&&r!l&&!r
51531
MC/DC0%0/3
$Declare::Constraints::Simple::Library::Base::FAIL_MESSAGE || $msg || $Declare::Constraints::Simple::Library::Base::FAIL_MESSAGE_DEFAULT
$Declare::Constraints::Simple::Library::Base::FAIL_MESSAGE $msg $Declare::Constraints::Simple::Library::Base::FAIL_MESSAGE_DEFAULT
Truth table75%3/4
A or B || C
A= $Declare::Constraints::Simple::Library::Base::FAIL_MESSAGEB= $msgC= $Declare::Constraints::Simple::Library::Base::FAIL_MESSAGE_DEFAULT
ABCresult
1XX1
01X1
0011
0000
209 $FAIL_MESSAGE || $msg || $FAIL_MESSAGE_DEFAULT)
210 unless $result_obj->is_valid;
211 605 return $result_obj;
212 }
213  
214 =head2 _false($msg)
215  
216 Returns a non-valid result object, with it's message set to C<$msg>.
217  
218 =head2 _true()
219  
220 Returns a valid result object.
221  
222 =cut
223  
224 95 ▶sub _false { _result(0, @_) }
Subroutine _false: called CC=1 SCAR=0.0
225 331 ▶sub _true { _result(1, @_) }
Subroutine _true: called CC=1 SCAR=0.0
226  
227 =head2 _info($info)
228  
229 Sets the current failure info to use in the stack info part.
230  
231 =cut
232  
233 34 ▶sub _info { $FAIL_INFO = shift }
Subroutine _info: called CC=1 SCAR=0.0
234  
235 =head2 _apply_checks($value, \@constraints, [$info])
236  
237 This applies all constraints in the C<\@constraints> array reference to
238 the passed C<$value>. You can optionally specify an C<$info> string to be
239 used in the stack of the newly created non-valid results.
240  
241 =cut
242  
243 165 ▶sub _apply_checks {
Subroutine _apply_checks: called CC=5 SCAR=16.1
244 165 my ($value, $checks, $info) = @_;
245 165 ▶ $checks ||= [];
Condition50%1/2
$checks ||= []
l!l
1650
MC/DC0%0/1
$checks ||= []
$checks
Truth table50%1/2
A
A= $checks
Aresult
11
00
246 165 ▶ $FAIL_INFO = $info if $info;
Branch: 1 branch
BranchTrueFalseTotal
if $info 138 27 165
247 165 for (@$checks) {
248 165 my $result = $_->($value);
249 165 ▶ return $result unless $result->is_valid;
Branch: 1 branch
BranchTrueFalseTotal
unless $result->is_valid 30 135 165
250 }
251 135 return _true;
252 }
253  
254 =head2 _listify($value)
255  
256 Puts C<$value> into an array reference and returns it, if it isn't
257 already one.
258  
259 =cut
260  
261 100 ▶sub _listify {
Subroutine _listify: called CC=2 SCAR=6.9
262 100 my ($value) = @_;
263 100 ▶ return (ref($value) eq 'ARRAY' ? $value : [$value]);
Branch: 1 branch
BranchTrueFalseTotal
ref $value eq 'ARRAY' ? : 4 96 100
264 }
265  
266 =head2 _with_message($msg, $closure, @args)
267  
268 This is the internal version of the general C<Message> constraint. It
269 sets the current overriden message to C<$msg> and executes the
270 C<$closure> with C<@args> as arguments.
271  
272 =cut
273  
274 14 ▶sub _with_message {
Subroutine _with_message: called CC=1 SCAR=0.0
275 14 my ($msg, $closure, @args) = @_;
276 14 local $FAIL_MESSAGE = $msg;
277 14 return $closure->(@args);
278 }
279  
280 =head2 _with_scope($scope_name, $constraint, @args)
281  
282 Applies the C<$constraint> to C<@args> in a newly created scope named
283 by C<$scope_name>.
284  
285 =cut
286  
287 8 ▶sub _with_scope {
Subroutine _with_scope: called CC=2 SCAR=7.1
288 8 my ($scope_name, $closure, @args) = @_;
289 local %SCOPES = ($scope_name => {})
290 8 ▶ unless exists $SCOPES{$scope_name};
Branch: 1 branch
BranchTrueFalseTotal
unless exists $Declare::Constraints::Simple::Library::Base::SCOPES{$scope_name} 8 0 8
291 8 return $closure->(@args);
292 }
293  
294 =head2 _set_result($scope, $name, $result)
295  
296 Stores the given C<$result> unter the name C<$name> in C<$scope>.
297  
298 =cut
299  
300 11 ▶sub _set_result {
Subroutine _set_result: called CC=1 SCAR=0.0
301 11 my ($scope, $name, $result) = @_;
302 11 $SCOPES{$scope}{result}{$name} = $result;
303 11 1;
304 }
305  
306 =head2 _get_result($scope, $name)
307  
308 Returns the result named C<$name> from C<$scope>.
309  
310 =cut
311  
312 8 ▶sub _get_result {
Subroutine _get_result: called CC=1 SCAR=0.0
313 8 my ($scope, $name) = @_;
314 8 return $SCOPES{$scope}{result}{$name};
315 }
316  
317 =head2 _has_result($scope, $name)
318  
319 Returns true only if such a result was registered already.
320  
321 =cut
322  
323 9 ▶sub _has_result {
Subroutine _has_result: called CC=1 SCAR=0.0
324 9 my ($scope, $name) = @_;
325 9 return exists $SCOPES{$scope}{result}{$name};
326 }
327  
328 =head1 SEE ALSO
329  
330 L<Declare::Constraints::Simple>, L<Declare::Constraints::Simple::Library>
331  
332 =head1 AUTHOR
333  
334 Robert 'phaylon' Sedlacek C<E<lt>phaylon@dunkelheit.atE<gt>>
335  
336 =head1 LICENSE AND COPYRIGHT
337  
338 This module is free software, you can redistribute it and/or modify it
339 under the same terms as perl itself.
340  
341 =cut
342  
343 14 1;
« Simple/Library/Operators.pm ↑ Summary Simple/Library/Numerical.pm »