Debian Codegraph @

README

raw
1 NAME
2
3 Data::Checks - Value constraint checking
4
5 SYNOPSIS
6
7 With Signature::Attribute::Checked:
8
9 use v5.26;
10 use Sublike::Extended 0.29 'sub';
11 use Signature::Attribute::Checked;
12
13 use Data::Checks qw( Str );
14
15 sub greet ( $message :Checked(Str) ) {
16 say "Hello, $message";
17 }
18
19 greet( "world" ); # is fine
20 greet( undef ); # throws an exception
21
22 With Object::Pad::FieldAttr::Checked:
23
24 use v5.22;
25 use Object::Pad;
26 use Object::Pad::FieldAttr::Checked;
27
28 use Data::Checks qw( Str );
29
30 class Datum {
31 field $name :param :reader :Checked(Str);
32 }
33
34 my $x = Datum->new( name => "something" ); # is fine
35 my $y = Datum->new( name => undef ); # throws an exception
36
37 With Syntax::Operator::Is on Perl v5.38 or later:
38
39 use v5.38;
40 use Syntax::Operator::Is;
41
42 use Data::Checks qw( Num Object );
43
44 my $x = ...;
45
46 if($x is Num) {
47 say "x can be used as a number";
48 }
49 elsif($x is Object) {
50 say "x can be used as an object";
51 }
52
53 DESCRIPTION
54
55 This module provides functions that implement various value constraint
56 checking behaviours. These are the parts made visible by the use
57 Data::Checks ... import line, in Perl code.
58
59 It also provides the underlying common framework XS functions to assist
60 in writing modules that actually implement such constraint checking.
61 These parts are not visible in Perl code, but instead made visible at
62 the XS level by the #include "DataChecks.h" directive.
63
64 See the "SYNOPSIS" section above for several examples of other CPAN
65 modules that make direct use of these constraint checks.
66
67 CONSTRAINTS
68
69 The following constraint checks are inspired by the same-named ones in
70 Types::Standard. They may be called fully-qualified, or imported
71 lexically into the calling scope.
72
73 Note to users familiar with Types::Standard: some of these functions
74 behave slightly differently. In particular, these constraints are
75 generally happy to accept an object reference to a class that provides
76 a conversion overload, whereas the ones in Types::Standard often are
77 not. Additionally functions that are parametric take their parameters
78 in normal Perl function argument lists, not wrapped in additional array
79 references.
80
81 Defined
82
83 Defined()
84
85 Accepts any defined value, rejects only undef.
86
87 Object
88
89 Object()
90
91 Accepts any blessed object reference, rejects non-references or
92 references to unblessed data.
93
94 Str
95
96 Str()
97
98 Accepts any defined non-reference value, or a reference to an object in
99 a class that overloads stringification. Rejects undefined, unblessed
100 references, or references to objects in classes that do not overload
101 stringification.
102
103 StrEq
104
105 StrEq($s)
106 StrEq($s1, $s2, ...)
107
108 Since version 0.05.
109
110 Accepts any value that passes the "Str" check, and additionally is
111 exactly equal to any of the given strings.
112
113 StrMatch
114
115 StrMatch(qr/pattern/)
116
117 Since version 0.08.
118
119 Accepts any value that passes the "Str" check, and additionally matches
120 the given regexp pattern.
121
122 Remember that the pattern must be supplied as a qr/.../ expression, not
123 simply m/.../ or /.../.
124
125 Num
126
127 Num()
128
129 Accepts any defined non-reference value that is either a plain number,
130 or a string that could be used as one without warning, or a reference
131 to an object in a class that overloads numification.
132
133 Rejects undefined, not-a-number, strings that would raise a warning if
134 converted to a number, unblessed references, or references to objects
135 in classes that do not overload numification.
136
137 NumGT
138
139 NumGE
140
141 NumLE
142
143 NumLT
144
145 NumGT($bound)
146 NumGE($bound)
147 NumLE($bound)
148 NumLT($bound)
149
150 Since version 0.05.
151
152 Accepts any value that passes the "Num" check, and additionally is
153 within the bound given. NumGT and NumLT exclude the bound value itself,
154 NumGE and NumLE include it.
155
156 NumRange
157
158 NumRange($boundge, $boundlt)
159
160 Since version 0.05.
161
162 Accepts any value that passes the "Num" check, and additionally is
163 between the two bounds given. The lower bound is inclusive, and the
164 upper bound is exclusive.
165
166 This choice is made so that a set of NumRange constraints can easily be
167 created that cover distinct sets of numbers:
168
169 NumRange(0, 10), NumRange(10, 20), NumRange(20, 30), ...
170
171 To implement checks with both lower and upper bounds but other kinds of
172 inclusivity, use two Num... checks combined with an All(). For example,
173 to test between 0 and 100 inclusive at both ends:
174
175 All(NumGE(0), NumLE(100))
176
177 Combinations like this are internally implemented as efficiently as a
178 single NumRange() constraint.
179
180 NumEq
181
182 NumEq($n)
183 NumEq($n1, $n2, ...)
184
185 Since version 0.05.
186
187 Accepts any value that passes the "Num" check, and additionally is
188 exactly equal to any of the given numbers.
189
190 Isa
191
192 Isa($classname)
193
194 Since version 0.04.
195
196 Accepts any blessed object reference to an instance of the given class
197 name, or a subclass derived from it (i.e. anything accepted by the isa
198 operator).
199
200 Can
201
202 Can($methodname)
203 Can($methodname1, $methodname2, ...)
204
205 Since version 0.11.
206
207 Accepts any blessed object reference to an instance in a class, or a
208 class name directly, that has the all of the given method names (i.e.
209 anything that passes a ->can test on every name).
210
211 To accept only object references and not package names, combine this
212 check with Object by using the All combination:
213
214 All(Object, Can($methodname, ...))
215
216 ArrayRef
217
218 ArrayRef()
219
220 Since version 0.07.
221
222 Accepts any plain reference to an array, or any object reference to an
223 instance of a class that provides an array dereference overload.
224
225 HashRef
226
227 HashRef()
228
229 Since version 0.07.
230
231 Accepts any plain reference to a hash, or any object reference to an
232 instance of a class that provides a hash dereference overload.
233
234 Callable
235
236 Callable()
237
238 Since version 0.06.
239
240 Accepts any plain reference to a subroutine, or any object reference to
241 an instance of a class that provides a subroutine dereference overload.
242
243 Maybe
244
245 Maybe($C)
246
247 Since version 0.04.
248
249 Accepts undef in addition to anything else accepted by the given
250 constraint.
251
252 Any
253
254 Any($C1, $C2, ...)
255
256 Since version 0.07.
257
258 Accepts a value that is accepted by at least one of the given
259 constraints. Rejects if none of them accept it.
260
261 At least one constraint is required; it is an error to try to call
262 Any() with no arguments. If you need a constraint that accepts any
263 value at all, see "All".
264
265 $C1 | $C2 | ...
266
267 Since version 0.08.
268
269 This function is used to implement | operator overloading, so
270 constraint checks can be written using this more convenient syntax.
271
272 All
273
274 All($C1, $C2, ...)
275 All()
276
277 Since version 0.07.
278
279 Accepts a value that is accepted by every one of the given constraints.
280 Rejects if at least one of them rejects it.
281
282 Note that if no constraints are given, this accepts all possible
283 values. This may be useful as an "accept-all" fallback case for
284 generated code, or other situations where it is required to provide a
285 constraint check but you do not wish to constraint allowed values.
286
287 CONSTRAINT METHODS
288
289 While not intended to be called from regular Perl code, these
290 constraints still act like objects with the following methods.
291
292 check
293
294 $ok = $constraint->check( $value );
295
296 Since version 0.09.
297
298 Returns a boolean value indicating whether the constraint accepts the
299 given value.
300
301 XS FUNCTIONS
302
303 The following functions are provided by the DataChecks.h header file
304 for use in XS modules that implement value constraint checking.
305
306 boot_data_checks
307
308 void boot_data_checks(double ver);
309
310 Call this function from your BOOT section in order to initialise the
311 module and load the rest of the support functions.
312
313 ver should either be 0 or a decimal number for the module version
314 requirement; e.g.
315
316 boot_data_checks(0.01);
317
318 make_checkdata
319
320 struct DataChecks_Checker *make_checkdata(SV *checkspec);
321
322 Creates a struct DataChecks_Checker structure, which wraps the intent
323 of the value constraint check. The returned value is used as the
324 checker argument for the remaining functions.
325
326 The constraint check itself is specified by the SV given by checkspec,
327 which should come directly from the user code. The constraint check may
328 be specified in any of three ways:
329
330 * An object reference in a class which has a check method. Value
331 checks will be invoked as
332
333 $ok = $checkerobj->check( $value );
334
335 * A package name as a plain string of a package which has a check
336 method. Value checks will be invoked as
337
338 $ok = $checkerpkg->check( $value );
339
340 * A code reference. Value checks will be invoked with a single
341 argument, as
342
343 $ok = $checkersub->( $value );
344
345 Since version 0.09 this form is now deprecated, because it does not
346 easily support a way to query the constraint for its name or
347 stringified form, which is useful when generating error messages.
348
349 * Additionally, the constraint check functions provided by this
350 module may be implemented using any of the above mechanisms, or may
351 use an unspecified fourth different mechanism. Outside code should
352 not rely on what that mechanism may be.
353
354 Once constructed into a checker structure, the choice of which
355 implementation is used is fixed, and if a method lookup is involved its
356 result is stored directly as a CV pointer for efficiency of later
357 invocations. In either of the first two cases, the reference count on
358 the checkspec SV is increased to account for the argument value used on
359 each invocation. In the third case, the reference SV is not retained,
360 but the underlying CV it refers to has its reference count increased.
361
362 free_checkdata
363
364 void free_checkdata(struct DataChecks_Checker *checker);
365
366 Releases any stored SVs in the checker structure, and the structure
367 itself.
368
369 gen_assertmess
370
371 void gen_assertmess(struct DataChecks_Checker *checker, SV *name, SV *constraint);
372
373 Generates and stores a message string for the assert message to be used
374 by "make_assertop" and "assert_value". The message will take the form
375
376 NAME requires a value satisfying CONSTRAINT
377
378 Both name and constraint SVs used as temporary strings to generate the
379 stored message string. Neither SV is retained by the checker directly.
380
381 make_assertop
382
383 OP *make_assertop(struct DataChecks_Checker *checker, OP *argop);
384
385 Shortcut to calling "make_assertop_flags" with flags set to zero.
386
387 make_assertop_flags
388
389 OP *make_assertop_flags(struct DataChecks_Checker *checker, U32 flags, OP *argop);
390
391 Creates an optree fragment for a value check assertion operation.
392
393 Given an optree fragment in scalar context that generates an argument
394 value (argop), constructs a larger optree fragment that consumes it and
395 checks that the value is accepted by the constraint check given by
396 checker. The behaviours of the returned optree fragment will depend on
397 the flags.
398
399 If flags is OPf_WANT_VOID the returned optree will yield nothing.
400
401 If flags is zero, the return behaviour is not otherwise specified.
402
403 check_value
404
405 bool check_value(struct DataChecks_Checker *checker, SV *value);
406
407 Checks whether a given SV is accepted by the given constraint check,
408 returning true if so, or false if not.
409
410 assert_value
411
412 void assert_value(struct DataChecks_Checker *checker, SV *value);
413
414 Checks whether a given SV is accepted by the given constraint check,
415 throwing its assertion message if it does not.
416
417 TODO
418
419 * Unit constraints - maybe Int, some plain-only variants of Str and
420 Num, some reference types, etc...
421
422 * Structural constraints - HashOf, ArrayOf, etc...
423
424 * Think about a convenient name for inclusive-bounded numerical
425 constraints.
426
427 * Look into making const-folding work with the MIN .. MAX flip-flop
428 operator
429
430 * Performance enhancements for lists of many values in StrEq, NumEq,
431 etc
432
433 * Performance enhancement of Can by caching per package name
434
435 AUTHOR
436
437 Paul Evans <[email protected]>
438