5 Moose::Manual::Types - Moose's type system
9 Moose provides its own type system for attributes. You can also use
10 these types to validate method parameters with the help of a MooseX
13 Moose's type system is based on a combination of Perl 5's own
14 I<implicit> types and some Perl 6 concepts. You can easily create your
15 own subtypes with custom constraints, making it easy to express any
18 Types have names, and you can re-use them by name, making it easy to
19 share types throughout a large application.
21 Let us be clear that is not a "real" type system. Moose does not
22 magically make Perl start associating types with variables. This is
23 just an advanced parameter checking system which allows you to
24 associate a name with a constraint.
26 That said, it's still pretty damn useful, and we think it's one of the
27 things that makes Moose both fun and powerful. Taking advantage of the
28 type system makes it much easier to ensure that you are getting valid
29 data, and it also contributes greatly to code maintainability.
33 The basic Moose type hierarchy looks like this
57 In practice, the only difference between C<Any> and C<Item> is
58 conceptual. C<Item> is used as the top-level type in the hierarchy.
60 The rest of these types correspond to existing Perl concepts.
65 =item C<Bool> accepts C<1> for true, and any value that perl treats as false for false.
67 =item C<Maybe[`a]> accepts either C<`a> or C<undef>.
69 =item C<Num> accepts anything that perl thinks looks like a number (see L<Scalar::Util/looks_like_number>).
71 =item 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 be loaded beforehand for this to succeed.
73 =item C<FileHandle> accepts either an object of type L<IO::Handle> or a builtin perl filehandle (see L<Scalar::Util/openhandle>).
75 =item C<Object> accepts any blessed reference.
79 The types followed by "[`a]" can be parameterized. So instead of just
80 plain C<ArrayRef> we can say that we want C<ArrayRef[Int]> instead. We
81 can even do something like C<HashRef[ArrayRef[Str]]>.
83 The C<Maybe[`a]> type deserves a special mention. Used by itself, it
84 doesn't really mean anything (and is equivalent to C<Item>). When it
85 is parameterized, it means that the value is either C<undef> or the
86 parameterized type. So C<Maybe[Int]> means an integer or C<undef>.
88 For more details on the type hierarchy, see
89 L<Moose::Util::TypeConstraints>.
91 =head1 WHAT IS A TYPE?
93 It's important to realize that types are not classes (or
94 packages). Types are just objects (L<Moose::Meta::TypeConstraint>
95 objects, to be exact) with a name and a constraint. Moose maintains a
96 global type registry that lets it convert names like C<Num> into the
99 However, class names I<can be> type names. When you define a new class
100 using Moose, it defines an associated type name behind the scenes:
106 Now you can use C<'MyApp::User'> as a type name:
110 isa => 'MyApp::User',
113 However, for non-Moose classes there's no magic. You may have to
114 explicitly declare the class type. This is a bit muddled because Moose
115 assumes that any unknown type name passed as the C<isa> value for an
116 attribute is a class. So this works:
118 has 'birth_date' => (
123 In general, when Moose is presented with an unknown name, it assumes
124 that the name is a class:
126 subtype 'ModernDateTime'
128 => where { $_->year() >= 1980 }
129 => message { 'The date you provided is not modern enough' };
131 has 'valid_dates' => (
133 isa => 'ArrayRef[DateTime]',
136 Moose will assume that C<DateTime> is a class name in both of these
141 Moose uses subtypes in its built-in hierarchy. For example, C<Int> is
144 A subtype is defined in terms of a parent type and a constraint. Any
145 constraints defined by the parent(s) will be checked first, followed by
146 constraints defined by the subtype. A value must pass I<all> of these
147 checks to be valid for the subtype.
149 Typically, a subtype takes the parent's constraint and makes it more
152 A subtype can also define its own constraint failure message. This
153 lets you do things like have an error "The value you provided (20),
154 was not a valid rating, which must be a number from 1-10." This is
155 much friendlier than the default error, which just says that the value
156 failed a validation check for the type.
158 Here's a simple (and useful) subtype example:
160 subtype 'PositiveInt'
163 => message { "The number you provided, $_, was not a positive number" }
165 Note that the sugar functions for working with types are all exported
166 by L<Moose::Util::TypeConstraints>.
168 =head2 Creating a new type (that isn't a subtype)
170 You can also create new top-level types:
172 type 'FourCharacters' => where { defined $_ && length $_ == 4 };
174 In practice, this example is more or less the same as subtyping
175 C<Str>, except you have to check definedness yourself.
177 It's hard to find a case where you wouldn't want to subtype a very
178 broad type like C<Defined>, C<Ref> or C<Object>.
180 Defining a new top-level type is conceptually the same as subtyping
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 Once you're doing this, you should almost certainly look at the
201 L<MooseX::Types> module. This module makes it easy to create a "type library"
202 module, which can 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 write 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 One of the most powerful features of Moose's type system is its
217 coercions. A coercion is a way to convert from one type to another.
219 subtype 'ArrayRefOfInts'
220 => as 'ArrayRef[Int]';
222 coerce 'ArrayRefOfInts'
226 You'll note that we had to create a subtype rather than coercing
227 C<ArrayRef[Int]> directly. This is just a quirk of how Moose
230 Coercions, like type names, are global. This is I<another> reason why
231 it is good to namespace your types. Moose will I<never> try to coerce
232 a value unless you explicitly ask for it. This is done by setting the
233 C<coerce> attribute option to a true value:
239 isa => 'ArrayRefOfInts',
243 Foo->new( sizes => 42 );
245 This code example will do the right thing, and the newly created
246 object will have C<[ 42 ]> as its C<sizes> attribute.
250 Deep coercion is the coercion of type parameters for parameterized
251 types. Let's take these types as an example:
255 => where { /[a-f0-9]/i };
263 isa => 'ArrayRef[Int]',
267 If we try passing an array reference of hex numbers for the C<sizes>
268 attribute, Moose will not do any coercion.
270 However, you can define a set of subtypes to enable coercion between
271 two parameterized types.
273 subtype 'ArrayRefOfHexNums'
274 => as 'ArrayRef[HexNum]';
276 subtype 'ArrayRefOfInts'
277 => as 'ArrayRef[Int]';
279 coerce 'ArrayRefOfInts'
280 => from 'ArrayRefOfHexNums'
281 => via { [ map { hex } @{$_} ] };
283 Foo->new( sizes => [ 'a1', 'ff', '22' ] );
285 Now Moose will coerce the hex numbers to integers.
287 However, Moose does not attempt to chain coercions, so it will not
288 coerce a single hex number. To do that, we need to define a separate
291 coerce 'ArrayRefOfInts'
293 => via { [ hex $_ ] };
295 Yes, this can all get verbose, but coercion is tricky magic, and we
296 think it's best to make it explicit.
300 Moose allows you to say that an attribute can be of two or more
301 disparate types. For example, we might allow an C<Object> or
306 isa => 'Object | FileHandle',
309 Moose actually parses that string and recognizes that you are creating
310 a type union. The C<output> attribute will accept any sort of object,
311 as well as an unblessed file handle. It is up to you to do the right
312 thing for each of them in your code.
314 Whenever you use a type union, you should consider whether or not
315 coercion might be a better answer.
317 For our example above, we might want to be more specific, and insist
318 that output be an object with a C<print> method:
322 => where { $_->can('print') };
324 We can coerce file handles to an object that satisfies this condition
325 with a simple wrapper class:
338 my $fh = $self->handle();
343 Now we can define a coercion from C<FileHandle> to our wrapper class:
347 => via { FHWrapper->new( handle => $_ ) };
355 This pattern of using a coercion instead of a type union will help
356 make your class internals simpler.
358 =head1 TYPE CREATION HELPERS
360 The L<Moose::Util::TypeConstraints> module exports a number of helper
361 functions for creating specific kinds of types. These include
362 C<class_type>, C<role_type>, and C<maybe_type>. See the docs for
365 One helper worth noting is C<enum>, which allows you to create a
366 subtype of C<Str> that only allows the specified values:
368 enum 'RGB' => qw( red green blue );
370 This creates a type named C<RGB>.
372 =head1 ANONYMOUS TYPES
374 All of the type creation functions return a type object. This type
375 object can be used wherever you would use a type name, as a parent
376 type, or as the value for an attribute's C<isa> option:
380 isa => subtype('Int' => where { $_ > 0 }),
383 This is handy when you want to create a one-off type and don't want to
384 "pollute" the global namespace registry.
386 =head1 VALIDATING METHOD PARAMETERS
388 Moose does not provide any means of validating method
389 parameters. However, there are several MooseX extensions on CPAN which
392 The simplest and least sugary is L<MooseX::Params::Validate>. This
393 lets you validate a set of named parameters using Moose types:
396 use MooseX::Params::Validate;
400 my %params = validated_hash(
402 bar => { isa => 'Str', default => 'Moose' },
407 L<MooseX::Params::Validate> also supports coercions.
409 There are several more powerful extensions that support method
410 parameter validation using Moose types, including
411 L<MooseX::Method::Signatures>, which gives you a full-blown C<method>
414 method morning (Str $name) {
415 $self->say("Good morning ${name}!");
418 =head1 LOAD ORDER ISSUES
420 Because Moose types are defined at runtime, you may run into load
421 order problems. In particular, you may want to use a class's type
422 constraint before that type has been defined.
424 We have several recommendations for ameliorating this problem. First,
425 define I<all> of your custom types in one module,
426 C<MyApp::Types>. Second, load this module in all of your other
429 If you are still having load order problems, you can make use of the
430 C<find_type_constraint> function exported by
431 L<Moose::Util::TypeConstraints>:
433 class_type('MyApp::User')
434 unless find_type_constraint('MyApp::User');
436 This sort of "find or create" logic is simple to write, and will let
437 you work around load order issues.
441 Dave Rolsky E<lt>autarch@urth.orgE<gt>
443 =head1 COPYRIGHT AND LICENSE
445 Copyright 2009 by Infinity Interactive, Inc.
447 L<http://www.iinteractive.com>
449 This library is free software; you can redistribute it and/or modify
450 it under the same terms as Perl itself.