1Moose::Util::TypeConstrUasienrtsC(o3n)tributed Perl DocuMmoeonstea:t:iUotnil::TypeConstraints(3)
2
6 Moose::Util::TypeConstraints - Type constraint system for Moose
7
9 use Moose::Util::TypeConstraints;
10 type 'Num' => where { Scalar::Util::looks_like_number($_) };
12 subtype 'Natural'
14 => as 'Num'
15 => where { $_ > 0 };
16 subtype 'NaturalLessThanTen'
18 => as 'Natural'
19 => where { $_ < 10 }
20 => message { "This number ($_) is not less than ten!" };
21 coerce 'Num'
23 => from 'Str'
24 => via { 0+$_ };
25 enum 'RGBColors' => qw(red green blue);
27
29 This module provides Moose with the ability to create custom type con‐
30 traints to be used in attribute definition.
31 Important Caveat
33 This is NOT a type system for Perl 5. These are type constraints, and
35 they are not used by Moose unless you tell it to. No type inference is
36 performed, expression are not typed, etc. etc. etc.
37 This is simply a means of creating small constraint functions which can
39 be used to simplify your own type-checking code.
40 Slightly Less Important Caveat
42 It is almost always a good idea to quote your type and subtype names.
44 This is to prevent perl from trying to execute the call as an indirect
45 object call. This issue only seems to come up when you have a subtype
46 the same name as a valid class, but when the issue does arise it tends
47 to be quite annoying to debug.
48 So for instance, this:
50 subtype DateTime => as Object => where { $_->isa('DateTime') };
52 will Just Work, while this:
54 use DateTime;
56 subtype DateTime => as Object => where { $_->isa('DateTime') };
57 will fail silently and cause many headaches. The simple way to solve
59 this, as well as future proof your subtypes from classes which have yet
60 to have been created yet, is to simply do this:
61 use DateTime;
63 subtype 'DateTime' => as 'Object' => where { $_->isa('DateTime') };
64 Default Type Constraints
66 This module also provides a simple hierarchy for Perl 5 types, this
68 could probably use some work, but it works for me at the moment.
69 Any
71 Item
72 Bool
73 Undef
74 Defined
75 Value
76 Num
77 Int
78 Str
79 ClassName
80 Ref
81 ScalarRef
82 ArrayRef
83 HashRef
84 CodeRef
85 RegexpRef
86 GlobRef
87 FileHandle
88 Object
89 Role
90 Suggestions for improvement are welcome.
92 NOTE: The "Undef" type constraint does not work correctly in every
94 occasion, please use it sparringly.
95 NOTE: The "ClassName" type constraint is simply a subtype of string
97 which responds true to "isa('UNIVERSAL')". This means that your class
98 must be loaded for this type constraint to pass. I know this is not
99 ideal for all, but it is a saner restriction than most others.
100 Use with Other Constraint Modules
102 This module should play fairly nicely with other constraint modules
104 with only some slight tweaking. The "where" clause in types is expected
105 to be a "CODE" reference which checks it's first argument and returns a
106 bool. Since most constraint modules work in a similar way, it should be
107 simple to adapt them to work with Moose.
108 For instance, this is how you could use it with Declare::Con‐
110 straints::Simple to declare a completely new type.
111 type 'HashOfArrayOfObjects'
113 => IsHashRef(
114 -keys => HasLength,
115 -values => IsArrayRef( IsObject ));
116 For more examples see the t/204_example_w_DCS.t test file.
118 Here is an example of using Test::Deep and it's non-test related
120 "eq_deeply" function.
121 type 'ArrayOfHashOfBarsAndRandomNumbers'
123 => where {
124 eq_deeply($_,
125 array_each(subhashof({
126 bar => isa('Bar'),
127 random_number => ignore()
128 })))
129 };
130 For a complete example see the t/205_example_w_TestDeep.t test file.
132
134 Type Constraint Construction & Locating
135 create_type_constraint_union ($pipe_seperated_types ⎪ @type_con‐
137 straint_names)
138 Given string with $pipe_seperated_types or a list of @type_con‐
139 straint_names, this will return a Moose::Meta::TypeCon‐
140 straint::Union instance.
141 create_parameterized_type_constraint ($type_name)
143 Given a $type_name in the form of:
144 BaseType[ContainerType]
146 this will extract the base type and container type and build an
148 instance of Moose::Meta::TypeConstraint::Parameterized for it.
149 find_or_create_type_constraint ($type_name, ?$options_for_anon_type)
151 This will attempt to find or create a type constraint given the a
152 $type_name. If it cannot find it in the registry, it will see if
153 it should be a union or container type an create one if appropri‐
154 ate, and lastly if nothing can be found or created that way, it
155 will create an anon-type using the $options_for_anon_type HASH ref
156 to populate it. If the $options_for_anon_type is not specified (it
157 is "undef"), then it will not create anything and simply return.
158 find_type_constraint ($type_name)
160 This function can be used to locate a specific type constraint
161 meta-object, of the class Moose::Meta::TypeConstraint or a deriva‐
162 tive. What you do with it from there is up to you :)
163 get_type_constraint_registry
165 Fetch the Moose::Meta::TypeConstraint::Registry object which keeps
166 track of all type constraints.
167 list_all_type_constraints
169 This will return a list of type constraint names, you can then
170 fetch them using "find_type_constraint ($type_name)" if you want
171 to.
172 list_all_builtin_type_constraints
174 This will return a list of builtin type constraints, meaning, those
175 which are defined in this module. See the section labeled "Default
176 Type Constraints" for a complete list.
177 export_type_constraints_as_functions
179 This will export all the current type constraints as functions into
180 the caller's namespace. Right now, this is mostly used for testing,
181 but it might prove useful to others.
182 Type Constraint Constructors
184 The following functions are used to create type constraints. They will
186 then register the type constraints in a global store where Moose can
187 get to them if it needs to.
188 See the SYNOPSIS for an example of how to use these.
190 type ($name, $where_clause)
192 This creates a base type, which has no parent.
193 subtype ($name, $parent, $where_clause, ?$message)
195 This creates a named subtype.
196 subtype ($parent, $where_clause, ?$message)
198 This creates an unnamed subtype and will return the type constraint
199 meta-object, which will be an instance of Moose::Meta::TypeCon‐
200 straint.
201 enum ($name, @values)
203 This will create a basic subtype for a given set of strings. The
204 resulting constraint will be a subtype of "Str" and will match any
205 of the items in @values. It is case sensitive. See the SYNOPSIS
206 for a simple example.
207 NOTE: This is not a true proper enum type, it is simple a convient
209 constraint builder.
210 as This is just sugar for the type constraint construction syntax.
212 where
214 This is just sugar for the type constraint construction syntax.
215 message
217 This is just sugar for the type constraint construction syntax.
218 optimize_as
220 This can be used to define a "hand optimized" version of your type
221 constraint which can be used to avoid traversing a subtype con‐
222 straint heirarchy.
223 NOTE: You should only use this if you know what you are doing, all
225 the built in types use this, so your subtypes (assuming they are
226 shallow) will not likely need to use this.
227 Type Coercion Constructors
229 Type constraints can also contain type coercions as well. If you ask
231 your accessor to coerce, then Moose will run the type-coercion code
232 first, followed by the type constraint check. This feature should be
233 used carefully as it is very powerful and could easily take off a limb
234 if you are not careful.
235 See the SYNOPSIS for an example of how to use these.
237 coerce
239 from
240 This is just sugar for the type coercion construction syntax.
241 via This is just sugar for the type coercion construction syntax.
243 Namespace Management
245 unimport
247 This will remove all the type constraint keywords from the calling
248 class namespace.
249
251 All complex software has bugs lurking in it, and this module is no
252 exception. If you find a bug please either email me, or add the bug to
253 cpan-RT.
254
256 Stevan Little <stevan@iinteractive.com>
257
259 Copyright 2006, 2007 by Infinity Interactive, Inc.
260 <http://www.iinteractive.com>
262 This library is free software; you can redistribute it and/or modify it
264 under the same terms as Perl itself.
265perl v5.8.8 2007-09-06 Moose::Util::TypeConstraints(3)