1Mouse::Util::TypeConstrUasienrtsC(o3n)tributed Perl DocuMmoeunstea:t:iUotnil::TypeConstraints(3)
2
3
4

NAME

6       Mouse::Util::TypeConstraints - Type constraint system for Mouse
7

VERSION

9       This document describes Mouse version v2.5.9
10
11   SYNOPSIS
12         use Mouse::Util::TypeConstraints;
13
14         subtype 'Natural'
15             => as 'Int'
16             => where { $_ > 0 };
17
18         subtype 'NaturalLessThanTen'
19             => as 'Natural'
20             => where { $_ < 10 }
21             => message { "This number ($_) is not less than ten!" };
22
23         coerce 'Num'
24             => from 'Str'
25               => via { 0+$_ };
26
27         enum 'RGBColors' => qw(red green blue);
28
29         no Mouse::Util::TypeConstraints;
30

DESCRIPTION

32       This module provides Mouse with the ability to create custom type
33       constraints to be used in attribute definition.
34
35   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
40       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
45   Slightly Less Important Caveat
46       It is always a good idea to quote your type names.
47
48       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
52       For instance:
53
54         subtype DateTime => as Object => where { $_->isa('DateTime') };
55
56       will just work, while this:
57
58         use DateTime;
59         subtype DateTime => as Object => where { $_->isa('DateTime') };
60
61       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
65         use DateTime;
66         subtype 'DateTime' => as 'Object' => where { $_->isa('DateTime') };
67
68   Default Type Constraints
69       This module also provides a simple hierarchy for Perl 5 types, here is
70       that hierarchy represented visually.
71
72        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
94       NOTE: Any type followed by a type parameter "[`a]" can be
95       parameterized, this means you can say:
96
97         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
101       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
105       NOTE: The "Undef" type constraint for the most part works correctly
106       now, but edge cases may still exist, please use it sparingly.
107
108       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
112       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
116   Type Constraint Naming
117       Type name declared via this module can only contain alphanumeric
118       characters, colons (:), and periods (.).
119
120       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
125   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
132       For instance, this is how you could use it with
133       Declare::Constraints::Simple to declare a completely new type.
134
135         type 'HashOfArrayOfObjects',
136             {
137             where => IsHashRef(
138                 -keys   => HasLength,
139                 -values => IsArrayRef(IsObject)
140             )
141         };
142
143       Here is an example of using Test::Deep and it's non-test related
144       "eq_deeply" function.
145
146         type 'ArrayOfHashOfBarsAndRandomNumbers'
147             => where {
148                 eq_deeply($_,
149                     array_each(subhashof({
150                         bar           => isa('Bar'),
151                         random_number => ignore()
152                     })))
153               };
154

METHODS

156   "list_all_builtin_type_constraints -> (Names)"
157       Returns the names of builtin type constraints.
158
159   "list_all_type_constraints -> (Names)"
160       Returns the names of all the type constraints.
161

FUNCTIONS

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

THANKS

177       Much of this documentation was taken from
178       "Moose::Util::TypeConstraints"
179

SEE ALSO

181       Moose::Util::TypeConstraints
182
183
184
185perl v5.30.1                      2020-01-30   Mouse::Util::TypeConstraints(3)
Impressum