1 package Moose::Manual::Types;
3 # ABSTRACT: Moose's type system
11 Moose provides its own type system for attributes. You can also use
12 these types to validate method parameters with the help of a MooseX
15 Moose's type system is based on a combination of Perl 5's own
16 I<implicit> types and some Perl 6 concepts. You can create your
17 own subtypes with custom constraints, making it easy to express any
20 Types have names, and you can re-use them by name, making it easy to
21 share types throughout a large application.
23 However, this is not a "real" type system. Moose does not magically make Perl
24 start associating types with variables. This is just an advanced parameter
25 checking system which allows you to associate a name with a constraint.
27 That said, it's still pretty damn useful, and we think it's one of the
28 things that makes Moose both fun and powerful. Taking advantage of the
29 type system makes it much easier to ensure that you are getting valid
30 data, and it also contributes greatly to code maintainability.
34 The basic Moose type hierarchy looks like this
58 In practice, the only difference between C<Any> and C<Item> is
59 conceptual. C<Item> is used as the top-level type in the hierarchy.
61 The rest of these types correspond to existing Perl concepts.
68 C<Bool> accepts C<1> for true, and undef, 0, or the empty string as false.
72 C<Maybe[`a]> accepts either C<`a> or C<undef>.
76 C<Num> accepts anything that perl thinks looks like a number (see L<Scalar::Util/looks_like_number>).
80 C<ClassName> and C<RoleName> accept strings that are either the name of a class or the name of a role. The class/role must already be loaded when the constraint is checked.
84 C<FileHandle> accepts either an L<IO::Handle> object or a builtin perl filehandle (see L<Scalar::Util/openhandle>).
88 C<Object> accepts any blessed reference.
92 The types followed by "[`a]" can be parameterized. So instead of just
93 plain C<ArrayRef> we can say that we want C<ArrayRef[Int]> instead. We
94 can even do something like C<HashRef[ArrayRef[Str]]>.
96 The C<Maybe[`a]> type deserves a special mention. Used by itself, it
97 doesn't really mean anything (and is equivalent to C<Item>). When it
98 is parameterized, it means that the value is either C<undef> or the
99 parameterized type. So C<Maybe[Int]> means an integer or C<undef>.
101 For more details on the type hierarchy, see
102 L<Moose::Util::TypeConstraints>.
104 =head1 WHAT IS A TYPE?
106 It's important to realize that types are not classes (or
107 packages). Types are just objects (L<Moose::Meta::TypeConstraint>
108 objects, to be exact) with a name and a constraint. Moose maintains a
109 global type registry that lets it convert names like C<Num> into the
112 However, class names I<can be> type names. When you define a new class
113 using Moose, it defines an associated type name behind the scenes:
119 Now you can use C<'MyApp::User'> as a type name:
123 isa => 'MyApp::User',
126 However, for non-Moose classes there's no magic. You may have to
127 explicitly declare the class type. This is a bit muddled because Moose
128 assumes that any unknown type name passed as the C<isa> value for an
129 attribute is a class. So this works:
131 has 'birth_date' => (
136 In general, when Moose is presented with an unknown name, it assumes
137 that the name is a class:
139 subtype 'ModernDateTime'
141 => where { $_->year() >= 1980 }
142 => message { 'The date you provided is not modern enough' };
144 has 'valid_dates' => (
146 isa => 'ArrayRef[DateTime]',
149 Moose will assume that C<DateTime> is a class name in both of these
154 Moose uses subtypes in its built-in hierarchy. For example, C<Int> is
157 A subtype is defined in terms of a parent type and a constraint. Any
158 constraints defined by the parent(s) will be checked first, followed by
159 constraints defined by the subtype. A value must pass I<all> of these
160 checks to be valid for the subtype.
162 Typically, a subtype takes the parent's constraint and makes it more
165 A subtype can also define its own constraint failure message. This
166 lets you do things like have an error "The value you provided (20),
167 was not a valid rating, which must be a number from 1-10." This is
168 much friendlier than the default error, which just says that the value
169 failed a validation check for the type. The default error can, however,
170 be made more friendly by installing L<Devel::PartialDump> (version 0.14 or
171 higher), which Moose will use if possible to display the invalid value.
173 Here's a simple (and useful) subtype example:
175 subtype 'PositiveInt',
178 message { "The number you provided, $_, was not a positive number" };
180 Note that the sugar functions for working with types are all exported
181 by L<Moose::Util::TypeConstraints>.
185 Type names are global throughout the current Perl
186 interpreter. Internally, Moose maps names to type objects via a
187 L<registry|Moose::Meta::TypeConstraint::Registry>.
189 If you have multiple apps or libraries all using Moose in the same
190 process, you could have problems with collisions. We recommend that
191 you prefix names with some sort of namespace indicator to prevent
192 these sorts of collisions.
194 For example, instead of calling a type "PositiveInt", call it
195 "MyApp::Type::PositiveInt" or "MyApp::Types::PositiveInt". We
196 recommend that you centralize all of these definitions in a single
197 package, C<MyApp::Types>, which can be loaded by other classes in your
200 However, before you do this, you should look at the L<MooseX::Types>
201 module. This module makes it easy to create a "type library" module, which can
202 export your types as perl constants.
204 has 'counter' => (is => 'rw', isa => PositiveInt);
206 This lets you use a short name rather than needing to fully qualify the name
207 everywhere. It also allows you to easily create parameterized types:
209 has 'counts' => (is => 'ro', isa => HashRef[PositiveInt]);
211 This module will check your names at compile time, and is generally more
212 robust than the string type parsing for complex cases.
216 A coercion lets you tell Moose to automatically convert one type to another.
218 subtype 'ArrayRefOfInts',
221 coerce 'ArrayRefOfInts',
225 You'll note that we created a subtype rather than coercing C<ArrayRef[Int]>
226 directly. It's a bad idea to add coercions to the raw built in
229 Coercions are global, just like type names, so a coercion applied to a built
230 in type is seen by all modules using Moose types. This is I<another> reason
231 why it is good to namespace your types.
233 Moose will I<never> try to coerce a value unless you explicitly ask for
234 it. This is done by setting the C<coerce> attribute option to a true value:
240 isa => 'ArrayRefOfInts',
244 Foo->new( sizes => 42 );
246 This code example will do the right thing, and the newly created
247 object will have C<[ 42 ]> as its C<sizes> attribute.
251 Deep coercion is the coercion of type parameters for parameterized
252 types. Let's take these types as an example:
256 where { /[a-f0-9]/i };
264 isa => 'ArrayRef[Int]',
268 If we try passing an array reference of hex numbers for the C<sizes>
269 attribute, Moose will not do any coercion.
271 However, you can define a set of subtypes to enable coercion between
272 two parameterized types.
274 subtype 'ArrayRefOfHexNums',
275 as 'ArrayRef[HexNum]';
277 subtype 'ArrayRefOfInts',
280 coerce 'ArrayRefOfInts',
281 from 'ArrayRefOfHexNums',
282 via { [ map { hex } @{$_} ] };
284 Foo->new( sizes => [ 'a1', 'ff', '22' ] );
286 Now Moose will coerce the hex numbers to integers.
288 Moose does not attempt to chain coercions, so it will not
289 coerce a single hex number. To do that, we need to define a separate
292 coerce 'ArrayRefOfInts',
296 Yes, this can all get verbose, but coercion is tricky magic, and we
297 think it's best to make it explicit.
301 Moose allows you to say that an attribute can be of two or more
302 disparate types. For example, we might allow an C<Object> or
307 isa => 'Object | FileHandle',
310 Moose actually parses that string and recognizes that you are creating
311 a type union. The C<output> attribute will accept any sort of object,
312 as well as an unblessed file handle. It is up to you to do the right
313 thing for each of them in your code.
315 Whenever you use a type union, you should consider whether or not
316 coercion might be a better answer.
318 For our example above, we might want to be more specific, and insist
319 that output be an object with a C<print> method:
321 duck_type 'CanPrint', [qw(print)];
323 We can coerce file handles to an object that satisfies this condition
324 with a simple wrapper class:
337 my $fh = $self->handle();
342 Now we can define a coercion from C<FileHandle> to our wrapper class:
346 => via { FHWrapper->new( handle => $_ ) };
354 This pattern of using a coercion instead of a type union will help
355 make your class internals simpler.
357 =head1 TYPE CREATION HELPERS
359 The L<Moose::Util::TypeConstraints> module exports a number of helper
360 functions for creating specific kinds of types. These include
361 C<class_type>, C<role_type>, C<maybe_type>, and C<duck_type>. See the
364 One helper worth noting is C<enum>, which allows you to create a
365 subtype of C<Str> that only allows the specified values:
367 enum 'RGB', [qw( red green blue )];
369 This creates a type named C<RGB>.
371 =head1 ANONYMOUS TYPES
373 All of the type creation functions return a type object. This type
374 object can be used wherever you would use a type name, as a parent
375 type, or as the value for an attribute's C<isa> option:
379 isa => subtype( 'Int' => where { $_ > 0 } ),
382 This is handy when you want to create a one-off type and don't want to
383 "pollute" the global namespace registry.
385 =head1 VALIDATING METHOD PARAMETERS
387 Moose does not provide any means of validating method
388 parameters. However, there are several MooseX extensions on CPAN which
391 The simplest and least sugary is L<MooseX::Params::Validate>. This
392 lets you validate a set of named parameters using Moose types:
395 use MooseX::Params::Validate;
399 my %params = validated_hash(
401 bar => { isa => 'Str', default => 'Moose' },
406 L<MooseX::Params::Validate> also supports coercions.
408 There are several more powerful extensions that support method
409 parameter validation using Moose types, including
410 L<MooseX::Method::Signatures>, which gives you a full-blown C<method>
413 method morning ( Str $name ) {
414 $self->say("Good morning ${name}!");
417 =head1 LOAD ORDER ISSUES
419 Because Moose types are defined at runtime, you may run into load
420 order problems. In particular, you may want to use a class's type
421 constraint before that type has been defined.
423 In order to ameliorate this problem, we recommend defining I<all> of your
424 custom types in one module, C<MyApp::Types>, and then loading this module in
425 all of your other modules.