1Mouse::Util::TypeConstrUasienrtsC(o3n)tributed Perl DocuMmoeunstea:t:iUotnil::TypeConstraints(3)
2
6 Mouse::Util::TypeConstraints - Type constraint system for Mouse
7
9 This document describes Mouse version v2.5.6
10 SYNOPSIS
12 use Mouse::Util::TypeConstraints;
13 subtype 'Natural'
15 => as 'Int'
16 => where { $_ > 0 };
17 subtype 'NaturalLessThanTen'
19 => as 'Natural'
20 => where { $_ < 10 }
21 => message { "This number ($_) is not less than ten!" };
22 coerce 'Num'
24 => from 'Str'
25 => via { 0+$_ };
26 enum 'RGBColors' => qw(red green blue);
28 no Mouse::Util::TypeConstraints;
30
32 This module provides Mouse with the ability to create custom type
33 constraints to be used in attribute definition.
34 Important Caveat
36 This is NOT a type system for Perl 5. These are type constraints, and
37 they are not used by Mouse unless you tell it to. No type inference is
38 performed, expressions are not typed, etc. etc. etc.
39 A type constraint is at heart a small "check if a value is valid"
41 function. A constraint can be associated with an attribute. This
42 simplifies parameter validation, and makes your code clearer to read,
43 because you can refer to constraints by name.
44 Slightly Less Important Caveat
46 It is always a good idea to quote your type names.
47 This prevents Perl from trying to execute the call as an indirect
49 object call. This can be an issue when you have a subtype with the same
50 name as a valid class.
51 For instance:
53 subtype DateTime => as Object => where { $_->isa('DateTime') };
55 will just work, while this:
57 use DateTime;
59 subtype DateTime => as Object => where { $_->isa('DateTime') };
60 will fail silently and cause many headaches. The simple way to solve
62 this, as well as future proof your subtypes from classes which have yet
63 to have been created, is to quote the type name:
64 use DateTime;
66 subtype 'DateTime' => as 'Object' => where { $_->isa('DateTime') };
67 Default Type Constraints
69 This module also provides a simple hierarchy for Perl 5 types, here is
70 that hierarchy represented visually.
71 Any
73 Item
74 Bool
75 Maybe[`a]
76 Undef
77 Defined
78 Value
79 Str
80 Num
81 Int
82 ClassName
83 RoleName
84 Ref
85 ScalarRef
86 ArrayRef[`a]
87 HashRef[`a]
88 CodeRef
89 RegexpRef
90 GlobRef
91 FileHandle
92 Object
93 NOTE: Any type followed by a type parameter "[`a]" can be
95 parameterized, this means you can say:
96 ArrayRef[Int] # an array of integers
98 HashRef[CodeRef] # a hash of str to CODE ref mappings
99 Maybe[Str] # value may be a string, may be undefined
100 If Mouse finds a name in brackets that it does not recognize as an
102 existing type, it assumes that this is a class name, for example
103 "ArrayRef[DateTime]".
104 NOTE: The "Undef" type constraint for the most part works correctly
106 now, but edge cases may still exist, please use it sparingly.
107 NOTE: The "ClassName" type constraint does a complex package existence
109 check. This means that your class must be loaded for this type
110 constraint to pass.
111 NOTE: The "RoleName" constraint checks a string is a package name which
113 is a role, like 'MyApp::Role::Comparable'. The "Role" constraint checks
114 that an object does the named role.
115 Type Constraint Naming
117 Type name declared via this module can only contain alphanumeric
118 characters, colons (:), and periods (.).
119 Since the types created by this module are global, it is suggested that
121 you namespace your types just as you would namespace your modules. So
122 instead of creating a Color type for your My::Graphics module, you
123 would call the type My::Graphics::Types::Color instead.
124 Use with Other Constraint Modules
126 This module can play nicely with other constraint modules with some
127 slight tweaking. The "where" clause in types is expected to be a "CODE"
128 reference which checks it's first argument and returns a boolean. Since
129 most constraint modules work in a similar way, it should be simple to
130 adapt them to work with Mouse.
131 For instance, this is how you could use it with
133 Declare::Constraints::Simple to declare a completely new type.
134 type 'HashOfArrayOfObjects',
136 {
137 where => IsHashRef(
138 -keys => HasLength,
139 -values => IsArrayRef(IsObject)
140 )
141 };
142 Here is an example of using Test::Deep and it's non-test related
144 "eq_deeply" function.
145 type 'ArrayOfHashOfBarsAndRandomNumbers'
147 => where {
148 eq_deeply($_,
149 array_each(subhashof({
150 bar => isa('Bar'),
151 random_number => ignore()
152 })))
153 };
154
156 "list_all_builtin_type_constraints -> (Names)"
157 Returns the names of builtin type constraints.
158 "list_all_type_constraints -> (Names)"
160 Returns the names of all the type constraints.
161
163 "type $name => where { } ... -> Mouse::Meta::TypeConstraint"
164 "subtype $name => as $parent => where { } ... ->
165 Mouse::Meta::TypeConstraint"
166 "subtype as $parent => where { } ... -> Mouse::Meta::TypeConstraint"
167 "class_type ($class, ?$options) -> Mouse::Meta::TypeConstraint"
168 "role_type ($role, ?$options) -> Mouse::Meta::TypeConstraint"
169 "duck_type($name, @methods | \@methods) -> Mouse::Meta::TypeConstraint"
170 "duck_type(\@methods) -> Mouse::Meta::TypeConstraint"
171 "enum($name, @values | \@values) -> Mouse::Meta::TypeConstraint"
172 "enum (\@values) -> Mouse::Meta::TypeConstraint"
173 "coerce $type => from $another_type, via { }, ..."
174 "find_type_constraint(Type) -> Mouse::Meta::TypeConstraint"
175
177 Much of this documentation was taken from
178 "Moose::Util::TypeConstraints"
179
181 Moose::Util::TypeConstraints
182perl v5.28.0 2018-08-14 Mouse::Util::TypeConstraints(3)