=pod
=encoding utf-8
=for stopwords superset
=head1 NAME
Type::API::Constraint - a rule that a value can be checked against, to determine whether it passes or fails
=head1 INTERFACE
Implementations of this interface are objects and B<MUST> provide the
following methods:
=over
=item C<< $constraint->check($value) >>
Checks that the value meets the constraint. Under normal operation should
return true or false to indicate a pass or failure.
Exceptions should not be thrown when a value simply fails the constraint,
but may be used for other exceptional conditions. (For example, if the
check requires a database lookup to determine pass or failure, but the
database is unavailable.)
=item C<< $constraint->get_message($value) >>
Generates an message explaining that the value has failed the type
constraint, and returns this messages as a string. This method does not
need to check whether the value genuinely fails the constraint; it can
assume that the check method has already been called.
=back
Implementations B<MAY> advertise that they support this interface by
returning true for C<< $constraint->DOES("Type::API::Constraint") >>.
=head1 SEE ALSO
=head2 Implementations
The following CPAN classes are known to implement Type::API::Constraint:
=over
=item *
L<Moose::Meta::TypeConstraint> (and its subclasses)
=item *
L<MooseX::Meta::TypeDecorator>
=item *
L<Mouse::Meta::TypeConstraint>
=item *
L<MouseX::Meta::TypeDecorator>
=item *
L<Specio::Constraint::Simple> (and several other classes in the Specio distribution)
=item *
L<Type::Tiny> (and its subclasses)
=back
=head2 Consumers
Some tools can make use of objects implementing Type::API::Constraint:
=over
=item *
L<Data::Validator>
=item *
L<Function::Parameters/Experimental experimental feature: Type expressions>
=item *
L<Scalar::Does>
=item *
L<Type::Tie>
=back
Others, such as L<Moose> and L<Mouse> require type constraints that implement
a superset of this functionality.
=head1 AUTHOR
Toby Inkster E<lt>tobyink@cpan.orgE<gt>.
=head1 COPYRIGHT AND LICENCE
This software is copyright (c) 2013 by Toby Inkster.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
=head1 DISCLAIMER OF WARRANTIES
THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
=cut