plucky (3) Data::Checks.3pm.gz
NAME
"Data::Checks" - Value constraint checking
SYNOPSIS
With Signature::Attribute::Checked:
use v5.26;
use Sublike::Extended;
use Signature::Attribute::Checked;
use Data::Checks qw( Str );
extended sub greet ( $message :Checked(Str) ) {
say "Hello, $message";
}
greet( "world" ); # is fine
greet( undef ); # throws an exception
With Object::Pad::FieldAttr::Checked:
use v5.22;
use Object::Pad;
use Object::Pad::FieldAttr::Checked;
use Data::Checks qw( Str );
class Datum {
field $name :param :reader :Checked(Str);
}
my $x = Datum->new( name => "something" ); # is fine
my $y = Datum->new( name => undef ); # throws an exception
With Syntax::Operator::Is on Perl v5.38 or later:
use v5.38;
use Syntax::Operator::Is;
use Data::Checks qw( Num Object );
my $x = ...;
if($x is Num) {
say "x can be used as a number";
}
elsif($x is Object) {
say "x can be used as an object";
}
DESCRIPTION
This module provides functions that implement various value constraint checking behaviours. These are the
parts made visible by the "use Data::Checks ..." import line, in Perl code.
It also provides the underlying common framework XS functions to assist in writing modules that actually
implement such constraint checking. These parts are not visible in Perl code, but instead made visible at
the XS level by the "#include "DataChecks.h"" directive.
See the "SYNOPSIS" section above for several examples of other CPAN modules that make direct use of these
constraint checks.
CONSTRAINTS
The following constraint checks are inspired by the same-named ones in Types::Standard. They may be
called fully-qualified, or imported lexically into the calling scope.
Note to users familiar with "Types::Standard": some of these functions behave slightly differently. In
particular, these constraints are generally happy to accept an object reference to a class that provides
a conversion overload, whereas the ones in "Types::Standard" often are not. Additionally functions that
are parametric take their parameters in normal Perl function argument lists, not wrapped in additional
array references.
Defined
Defined()
Accepts any defined value, rejects only "undef".
Object
Object()
Accepts any blessed object reference, rejects non-references or references to unblessed data.
Str
Str()
Accepts any defined non-reference value, or a reference to an object in a class that overloads
stringification. Rejects undefined, unblessed references, or references to objects in classes that do not
overload stringification.
StrEq
StrEq($s)
StrEq($s1, $s2, ...)
Since version 0.05.
Accepts any value that passes the Str check, and additionally is exactly equal to any of the given
strings.
StrMatch
StrMatch(qr/pattern/)
Since version 0.08.
Accepts any value that passes the Str check, and additionally matches the given regexp pattern.
Remember that the pattern must be supplied as a "qr/.../" expression, not simply "m/.../" or "/.../".
Num
Num()
Accepts any defined non-reference value that is either a plain number, or a string that could be used as
one without warning, or a reference to an object in a class that overloads numification.
Rejects undefined, not-a-number, strings that would raise a warning if converted to a number, unblessed
references, or references to objects in classes that do not overload numification.
NumGT
NumGE
NumLE
NumLT
NumGT($bound)
NumGE($bound)
NumLE($bound)
NumLT($bound)
Since version 0.05.
Accepts any value that passes the Num check, and additionally is within the bound given. "NumGT" and
"NumLT" exclude the bound value itself, "NumGE" and "NumLE" include it.
NumRange
NumRange($boundge, $boundlt)
Since version 0.05.
Accepts any value that passes the Num check, and additionally is between the two bounds given. The lower
bound is inclusive, and the upper bound is exclusive.
This choice is made so that a set of "NumRange" constraints can easily be created that cover distinct
sets of numbers:
NumRange(0, 10), NumRange(10, 20), NumRange(20, 30), ...
To implement checks with both lower and upper bounds but other kinds of inclusivity, use two "Num..."
checks combined with an All(). For example, to test between 0 and 100 inclusive at both ends:
All(NumGE(0), NumLE(100))
Combinations like this are internally implemented as efficiently as a single NumRange() constraint.
NumEq
NumEq($n)
NumEq($n1, $n2, ...)
Since version 0.05.
Accepts any value that passes the Num check, and additionally is exactly equal to any of the given
numbers.
Isa
Isa($classname)
Since version 0.04.
Accepts any blessed object reference to an instance of the given class name, or a subclass derived from
it (i.e. anything accepted by the "isa" operator).
ArrayRef
ArrayRef()
Since version 0.07.
Accepts any plain reference to an array, or any object reference to an instance of a class that provides
an array dereference overload.
HashRef
HashRef()
Since version 0.07.
Accepts any plain reference to a hash, or any object reference to an instance of a class that provides a
hash dereference overload.
Callable
Callable()
Since version 0.06.
Accepts any plain reference to a subroutine, or any object reference to an instance of a class that
provides a subroutine dereference overload.
Maybe
Maybe($C)
Since version 0.04.
Accepts "undef" in addition to anything else accepted by the given constraint.
Any
Any($C1, $C2, ...)
Since version 0.07.
Accepts a value that is accepted by at least one of the given constraints. Rejects if none of them
accept it.
At least one constraint is required; it is an error to try to call Any() with no arguments. If you need a
constraint that accepts any value at all, see "All".
$C1 | $C2 | ...
Since version 0.08.
This function is used to implement "|" operator overloading, so constraint checks can be written using
this more convenient syntax.
All
All($C1, $C2, ...)
All()
Since version 0.07.
Accepts a value that is accepted by every one of the given constraints. Rejects if at least one of them
rejects it.
Note that if no constraints are given, this accepts all possible values. This may be useful as an
"accept-all" fallback case for generated code, or other situations where it is required to provide a
constraint check but you do not wish to constraint allowed values.
CONSTRAINT METHODS
While not intended to be called from regular Perl code, these constraints still act like objects with the
following methods.
check
$ok = $constraint->check( $value );
Since version 0.09.
Returns a boolean value indicating whether the constraint accepts the given value.
XS FUNCTIONS
The following functions are provided by the DataChecks.h header file for use in XS modules that implement
value constraint checking.
boot_data_checks
void boot_data_checks(double ver);
Call this function from your "BOOT" section in order to initialise the module and load the rest of the
support functions.
ver should either be 0 or a decimal number for the module version requirement; e.g.
boot_data_checks(0.01);
make_checkdata
struct DataChecks_Checker *make_checkdata(SV *checkspec);
Creates a "struct DataChecks_Checker" structure, which wraps the intent of the value constraint check.
The returned value is used as the checker argument for the remaining functions.
The constraint check itself is specified by the "SV" given by checkspec, which should come directly from
the user code. The constraint check may be specified in any of three ways:
• An object reference in a class which has a "check" method. Value checks will be invoked as
$ok = $checkerobj->check( $value );
• A package name as a plain string of a package which has a "check" method. Value checks will be
invoked as
$ok = $checkerpkg->check( $value );
• A code reference. Value checks will be invoked with a single argument, as
$ok = $checkersub->( $value );
Since version 0.09 this form is now deprecated, because it does not easily support a way to query the
constraint for its name or stringified form, which is useful when generating error messages.
• Additionally, the constraint check functions provided by this module may be implemented using any of
the above mechanisms, or may use an unspecified fourth different mechanism. Outside code should not
rely on what that mechanism may be.
Once constructed into a checker structure, the choice of which implementation is used is fixed, and if a
method lookup is involved its result is stored directly as a CV pointer for efficiency of later
invocations. In either of the first two cases, the reference count on the checkspec SV is increased to
account for the argument value used on each invocation. In the third case, the reference SV is not
retained, but the underlying CV it refers to has its reference count increased.
free_checkdata
void free_checkdata(struct DataChecks_Checker *checker);
Releases any stored SVs in the checker structure, and the structure itself.
gen_assertmess
void gen_assertmess(struct DataChecks_Checker *checker, SV *name, SV *constraint);
Generates and stores a message string for the assert message to be used by "make_assertop" and
"assert_value". The message will take the form
NAME requires a value satisfying CONSTRAINT
Both name and constraint SVs used as temporary strings to generate the stored message string. Neither SV
is retained by the checker directly.
make_assertop
OP *make_assertop(struct DataChecks_Checker *checker, OP *argop);
Shortcut to calling "make_assertop_flags" with flags set to zero.
make_assertop_flags
OP *make_assertop_flags(struct DataChecks_Checker *checker, U32 flags, OP *argop);
Creates an optree fragment for a value check assertion operation.
Given an optree fragment in scalar context that generates an argument value (argop), constructs a larger
optree fragment that consumes it and checks that the value is accepted by the constraint check given by
checker. The behaviours of the returned optree fragment will depend on the flags.
If flags is "OPf_WANT_VOID" the returned optree will yield nothing.
If flags is zero, the return behaviour is not otherwise specified.
check_value
bool check_value(struct DataChecks_Checker *checker, SV *value);
Checks whether a given SV is accepted by the given constraint check, returning true if so, or false if
not.
assert_value
void assert_value(struct DataChecks_Checker *checker, SV *value);
Checks whether a given SV is accepted by the given constraint check, throwing its assertion message if it
does not.
TODO
• Unit constraints - maybe "Int", some plain-only variants of "Str" and "Num", some reference types,
etc...
• Structural constraints - "HashOf", "ArrayOf", etc...
• Think about a convenient name for inclusive-bounded numerical constraints.
• Look into making const-folding work with the "MIN .. MAX" flip-flop operator
AUTHOR
Paul Evans <leonerd@leonerd.org.uk>