Type::Tiny - tiny, yet Moo-compatible type constraint |
Type::Tiny - tiny, yet Moo(se)-compatible type constraint
use Scalar::Util qw(looks_like_number); use Type::Tiny; my $NUM = "Type::Tiny"->new( name => "Number", constraint => sub { looks_like_number($_) }, message => sub { "$_ ain't a number" }, ); package Ermintrude { use Moo; has favourite_number => (is => "ro", isa => $NUM); } package Bullwinkle { use Moose; has favourite_number => (is => "ro", isa => $NUM); } package Maisy { use Mouse; has favourite_number => (is => "ro", isa => $NUM); }
This module is covered by the Type-Tiny stability policy.
the Type::Tiny manpage is a tiny class for creating Moose-like type constraint objects which are compatible with Moo, Moose and Mouse.
Maybe now we won't need to have separate MooseX, MouseX and MooX versions of everything? We can but hope...
This documents the internals of the Type::Tiny manpage. the Type::Tiny::Manual manpage is a better starting place if you're new.
new(%attributes)
Attributes are named values that may be passed to the constructor. For each attribute, there is a corresponding reader method. For example:
my $type = Type::Tiny->new( name => "Foo" ); print $type->name, "\n"; # says "Foo"
These are the attributes you are likely to be most interested in providing when creating your own type constraints, and most interested in reading when dealing with type constraint objects.
constraint
$_
) against the type constraint. The
coderef will not be called unless the value is known to pass any parent
type constraint (see parent
below).
Defaults to sub { 1 }
- i.e. a coderef that passes all values.
parent
If provided, must be a Type::Tiny object.
inlined
If constraint
(above) is a coderef generated via the Sub::Quote manpage, then
Type::Tiny may be able to automatically generate inlined
for you.
name
Optional; if not supplied will be an anonymous type constraint.
display_name
name
.
library
message
$_
does not validate
against the type constraint. Optional (there's a vaguely sensible default.)
coercion
Generally speaking this attribute should not be passed to the constructor; you should rely on the default lazily-built coercion object.
You may pass coercion => 1
to the constructor to inherit coercions
from the constraint's parent. (This requires the parent constraint to have
a coercion.)
my_methods
The following additional attributes are used for parameterizable (e.g.
ArrayRef
) and parameterized (e.g. ArrayRef[Int]
) type
constraints. Unlike Moose, these aren't handled by separate subclasses.
constraint_generator
name_generator
, inline_generator
,
and coercion_generator
attributes documented below are ignored.
Optional; providing a generator makes this type into a parameterizable type constraint.
name_generator
inline_generator
coercion_generator
deep_explanation
parameters
The following attributes should not be usually passed to the constructor; unless you're doing something especially unusual, you should rely on the default lazily-built return values.
compiled_check
$_[0]
) against the type constraint.
This coderef is expected to also handle all validation for the parent
type constraints.
complementary_type
moose_type
, mouse_type
It should rarely be necessary to obtain a the Moose::Meta::TypeConstraint manpage object from the Type::Tiny manpage because the the Type::Tiny manpage object itself should be usable pretty much anywhere a the Moose::Meta::TypeConstraint manpage is expected.
These methods return booleans indicating information about the type constraint. They are each tightly associated with a particular attribute. (See Attributes.)
has_parent
, has_library
, has_inlined
, has_constraint_generator
, has_inline_generator
, has_coercion_generator
, has_parameters
, has_message
, has_deep_explanation
has_coercion
is_anon
name
.
is_parameterized
, is_parameterizable
ArrayRef[Int]
)
or could potentially be (e.g. ArrayRef
).
The following methods are used for coercing and validating values against a type constraint:
check($value)
validate($value)
assert_valid($value)
check($value)
but dies if the value does not pass the type
constraint.
Yes, that's three very similar methods. Blame the Moose::Meta::TypeConstraint manpage whose API I'm attempting to emulate. :-)
assert_return($value)
assert_valid($value)
but returns the value if it passes the type
constraint.
This seems a more useful behaviour than assert_valid($value)
. I would
have just changed assert_valid($value)
to do this, except that there
are edge cases where it could break Moose compatibility.
get_message($value)
validate_explain($value, $varname)
validate
but instead of a string error message, returns an arrayref
of strings explaining the reasoning why the value does not meet the type
constraint, examining parent types, etc.
The $varname
is an optional string like '$foo'
indicating the
name of the variable being checked.
coerce($value)
$value
to this type.
assert_coerce($value)
$value
to this type. Throws an exception if this is
not possible.
These methods generate new type constraint objects that inherit from the constraint they are called upon:
create_child_type(%attributes)
where($coderef)
HashRef->where(sub { exists($_->{name}) })
. That said, you can
get a similar result using overloaded &
:
HashRef & sub { exists($_->{name}) }
child_type_class
parameterize(@parameters)
of(@parameters)
parameterize
. Use it like ArrayRef->of(Int)
.
plus_coercions($type1, $code1, ...)
plus_fallback_coercions($type1, $code1, ...)
plus_coercions
, but added at a lower priority.
minus_coercions($type1, ...)
no_coercions
These methods allow you to determine a type constraint's relationship to other type constraints in an organised hierarchy:
equals($other)
, is_subtype_of($other)
, is_supertype_of($other)
, is_a_type_of($other)
is_supertype_of
, but you get the idea, right?)
Note that these have a slightly DWIM side to them. If you create two the Type::Tiny::Class manpage objects which test the same class, they're considered equal. And:
my $subtype_of_Num = Types::Standard::Num->create_child_type; my $subtype_of_Int = Types::Standard::Int->create_child_type; $subtype_of_Int->is_subtype_of( $subtype_of_Num ); # true
strictly_equals($other)
, is_strictly_subtype_of($other)
, is_strictly_supertype_of($other)
, is_strictly_a_type_of($other)
parent
.
my $subtype_of_Num = Types::Standard::Num->create_child_type; my $subtype_of_Int = Types::Standard::Int->create_child_type; $subtype_of_Int->is_strictly_subtype_of( $subtype_of_Num ); # false
parents
Str
type constraint would return the list
(Value, Defined, Item, Any)
.
Due to a historical misunderstanding, this differs from the Moose
implementation of the parents
method. In Moose, parents
only returns the
immediate parent type constraints, and because type constraints only have
one immediate parent, this is effectively an alias for parent
. The
extension module the MooseX::Meta::TypeConstraint::Intersection manpage is the only
place where multiple type constraints are returned; and they are returned
as an arrayref in violation of the base class' documentation. I'm keeping
my behaviour as it seems more useful. >
find_parent($coderef)
$_
. Returns undef if there is no match.
In list context also returns the number of type constraints which had been looped through before the matching constraint was found.
coercibles
type_parameter
( ArrayRef[Int] )->type_parameter; # returns Int ( ArrayRef[Int] )->parent; # returns ArrayRef
Note that parameterizable type constraints can perfectly legitimately take
multiple parameters (several off the parameterizable type constraints in
the Types::Standard manpage do). This method only returns the first such parameter.
Attributes related to parameterizable and parameterized types
documents the parameters
attribute, which returns an arrayref of all
the parameters.
The following methods are used to generate strings of Perl code which
may be pasted into stringy eval
uated subs to perform type checks:
can_be_inlined
inline_check($varname)
print( Types::Standard::Num->inline_check('$foo') );
prints the following output:
(!ref($foo) && Scalar::Util::looks_like_number($foo))
For Moose-compat, there is an alias _inline_check
for this method.
inline_assert($varname)
inline_check
but outputs a statement of the form:
die ... unless ...;
Note that if this type has a custom error message, the inlined code will ignore this custom message!!
qualified_name
"MyLib::MyType"
sort of name. Otherwise, returns the same as name
.
isa($class)
, can($method)
, AUTOLOAD(@args)
If Mouse is loaded, then isa
mocks Mouse::Meta::TypeConstraint.
DOES($role)
See also the Type::API::Constraint manpage, etc.
TIESCALAR
, TIEARRAY
, TIEHASH
use Types::Standard qw(Int); tie my @list, Int; push @list, 123, 456; # ok push @list, "Hello"; # dies
The following methods exist for Moose/Mouse compatibility, but do not do anything useful.
compile_type_constraint
hand_optimized_type_constraint
has_hand_optimized_type_constraint
inline_environment
meta
assert_return
.
On Perl 5.10.1 and above, smart match is overloaded to call check
.
The ==
operator is overloaded to call equals
.
The <
and >
operators are overloaded to call is_subtype_of
and is_supertype_of
.
The ~
operator is overloaded to call complementary_type
.
The |
operator is overloaded to build a union of two type constraints.
See the Type::Tiny::Union manpage.
The &
operator is overloaded to build the intersection of two type
constraints. See the Type::Tiny::Intersection manpage.
Previous versions of Type::Tiny would overload the +
operator to
call plus_coercions
or plus_fallback_coercions
as appropriate.
Support for this was dropped after 0.040.
Type::Tiny::SUPPORT_SMARTMATCH
$Type::Tiny::DD
Otherwise Type::Tiny uses it's own routine to dump data structures.
$DD
may then be set to a number to limit the lengths of the
dumps. (Default limit is 72.)
This is a package variable (rather than get/set class methods) to allow for easy localization.
Please report any bugs to http://rt.cpan.org/Dist/Display.html.
IRC: > support is available through in the #moops > channel on irc.perl.org.
the Type::Tiny::Manual manpage, the Type::API manpage.
the Type::Library manpage, the Type::Utils manpage, the Types::Standard manpage, the Type::Coercion manpage.
the Type::Tiny::Class manpage, the Type::Tiny::Role manpage, the Type::Tiny::Duck manpage, the Type::Tiny::Enum manpage, the Type::Tiny::Union manpage, the Type::Tiny::Intersection manpage.
the Moose::Meta::TypeConstraint manpage, the Mouse::Meta::TypeConstraint manpage.
Toby Inkster <tobyink@cpan.org>.
Thanks to Matt S Trout for advice on Moo integration.
This software is copyright (c) 2013-2014 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.
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.
Type::Tiny - tiny, yet Moo-compatible type constraint |