Mouse::Util::TypeConstUsertContributed Perl DocMouse::Util::TypeConstraints(3)NAMEMouse::Util::TypeConstraints - Type constraint system for Mouse
VERSION
This document describes Mouse version 1.02
SYNOPSIS
use Mouse::Util::TypeConstraints;
subtype 'Natural'
=> as 'Int'
=> where { $_ > 0 };
subtype 'NaturalLessThanTen'
=> as 'Natural'
=> where { $_ < 10 }
=> message { "This number ($_) is not less than ten!" };
coerce 'Num'
=> from 'Str'
=> via { 0+$_ };
enum 'RGBColors' => qw(red green blue);
no Mouse::Util::TypeConstraints;
DESCRIPTION
This module provides Mouse with the ability to create custom type
constraints to be used in attribute definition.
Important Caveat
This is NOT a type system for Perl 5. These are type constraints, and
they are not used by Mouse unless you tell it to. No type inference is
performed, expressions are not typed, etc. etc. etc.
A type constraint is at heart a small "check if a value is valid"
function. A constraint can be associated with an attribute. This
simplifies parameter validation, and makes your code clearer to read,
because you can refer to constraints by name.
Slightly Less Important Caveat
It is always a good idea to quote your type names.
This prevents Perl from trying to execute the call as an indirect
object call. This can be an issue when you have a subtype with the same
name as a valid class.
For instance:
subtype DateTime => as Object => where { $_->isa('DateTime') };
will just work, while this:
use DateTime;
subtype DateTime => as Object => where { $_->isa('DateTime') };
will fail silently and cause many headaches. The simple way to solve
this, as well as future proof your subtypes from classes which have yet
to have been created, is to quote the type name:
use DateTime;
subtype 'DateTime' => as 'Object' => where { $_->isa('DateTime') };
Default Type Constraints
This module also provides a simple hierarchy for Perl 5 types, here is
that hierarchy represented visually.
Any
Item
Bool
Maybe[`a]
Undef
Defined
Value
Str
Num
Int
ClassName
RoleName
Ref
ScalarRef
ArrayRef[`a]
HashRef[`a]
CodeRef
RegexpRef
GlobRef
FileHandle
Object
NOTE: Any type followed by a type parameter "[`a]" can be
parameterized, this means you can say:
ArrayRef[Int] # an array of integers
HashRef[CodeRef] # a hash of str to CODE ref mappings
Maybe[Str] # value may be a string, may be undefined
If Mouse finds a name in brackets that it does not recognize as an
existing type, it assumes that this is a class name, for example
"ArrayRef[DateTime]".
NOTE: The "Undef" type constraint for the most part works correctly
now, but edge cases may still exist, please use it sparingly.
NOTE: The "ClassName" type constraint does a complex package existence
check. This means that your class must be loaded for this type
constraint to pass.
NOTE: The "RoleName" constraint checks a string is a package name which
is a role, like 'MyApp::Role::Comparable'. The "Role" constraint checks
that an object does the named role.
Type Constraint Naming
Type name declared via this module can only contain alphanumeric
characters, colons (:), and periods (.).
Since the types created by this module are global, it is suggested that
you namespace your types just as you would namespace your modules. So
instead of creating a Color type for your My::Graphics module, you
would call the type My::Graphics::Types::Color instead.
Use with Other Constraint Modules
This module can play nicely with other constraint modules with some
slight tweaking. The "where" clause in types is expected to be a "CODE"
reference which checks it's first argument and returns a boolean. Since
most constraint modules work in a similar way, it should be simple to
adapt them to work with Mouse.
For instance, this is how you could use it with
Declare::Constraints::Simple to declare a completely new type.
type 'HashOfArrayOfObjects',
{
where => IsHashRef(
-keys => HasLength,
-values => IsArrayRef(IsObject)
)
};
Here is an example of using Test::Deep and it's non-test related
"eq_deeply" function.
type 'ArrayOfHashOfBarsAndRandomNumbers'
=> where {
eq_deeply($_,
array_each(subhashof({
bar => isa('Bar'),
random_number => ignore()
})))
};
METHODS
"list_all_builtin_type_constraints -> (Names)"
Returns the names of builtin type constraints.
"list_all_type_constraints -> (Names)"
Returns the names of all the type constraints.
FUNCTIONS
"type $name => where { } ... -> Mouse::Meta::TypeConstraint"
"subtype $name => as $parent => where { } ... ->
Mouse::Meta::TypeConstraint"
"subtype as $parent => where { } ... -> Mouse::Meta::TypeConstraint"
"class_type ($class, ?$options) -> Mouse::Meta::TypeConstraint"
"role_type ($role, ?$options) -> Mouse::Meta::TypeConstraint"
"duck_type($name, @methods | \@methods) -> Mouse::Meta::TypeConstraint"
"duck_type(\@methods) -> Mouse::Meta::TypeConstraint"
"enum($name, @values | \@values) -> Mouse::Meta::TypeConstraint"
"enum (\@values) -> Mouse::Meta::TypeConstraint"
"coerce $type => from $another_type, via { }, ..."
"find_type_constraint(Type) -> Mouse::Meta::TypeConstraint"
THANKS
Much of this documentation was taken from
"Moose::Util::TypeConstraints"
SEE ALSO
Moose::Util::TypeConstraints
perl v5.14.2 2012-08-27 Mouse::Util::TypeConstraints(3)
