lib/Moose/Manual/Types.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 Moose::Manual::Types - Moose's type system
   6
   7 =head1 TYPES IN PERL?
   8
   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
  11 module.
  12
  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
  16 sort of validation.
  17
  18 Types have names, and you can re-use them by name, making it easy to
  19 share types throughout a large application.
  20
  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.
  25
  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.
  30
  31 =head1 THE TYPES
  32
  33 The basic Moose type hierarchy looks like this
  34
  35   Any
  36   Item
  37       Bool
  38       Maybe[`a]
  39       Undef
  40       Defined
  41           Value
  42               Num
  43                 Int
  44               Str
  45                 ClassName
  46           Ref
  47               ScalarRef
  48               ArrayRef[`a]
  49               HashRef[`a]
  50               CodeRef
  51               RegexpRef
  52               GlobRef
  53                 FileHandle
  54               Object
  55                 Role
  56
  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.
  59
  60 The rest of these types correspond to existing Perl concepts. For
  61 example, a C<Num> is anything that Perl thinks looks like a number. An
  62 C<Object> is a blessed reference, etc.
  63
  64 The types followed by "[`a]" can be parameterized. So instead of just
  65 plain C<ArrayRef> we can say that we want C<ArrayRef[Int]> instead. We
  66 can even do something like C<HashRef[ArrayRef[Str]]>.
  67
  68 The C<Maybe[`a]> type deserves a special mention. Used by itself, it
  69 doesn't really mean anything (and is equivalent to C<Item>). When it
  70 is parameterized, it means that the value is either C<undef> or the
  71 parameterized type. So C<Maybe[Int]> means an integer or C<undef>
  72
  73 For more details on the type hierarchy, see
  74 L<Moose::Util::TypeConstraints>.
  75
  76 =head1 WHAT IS A TYPE?
  77
  78 It's important to realize that types are not classes (or
  79 packages). Types are just objects (L<Moose::Meta::TypeConstraint>
  80 objects, to be exact) with a name and a constraint. Moose maintains a
  81 global type registry that lets it convert names like "Num" into the
  82 appropriate object.
  83
  84 However, class names I<can be> type names. When you define a new class
  85 using Moose, it defines an associated type name behind the scenes:
  86
  87   package MyApp::User;
  88
  89   use Moose;
  90
  91 Now you can use C<'MyApp::User'> as a type name:
  92
  93   has creator => (
  94       is  => 'rw',
  95       isa => 'MyApp::User',
  96   );
  97
  98 However, for non-Moose classes there's no magic. You may have to
  99 explicitly declare the class type. This is a bit muddled because Moose
 100 assumes that any unknown type name passed as the C<isa> value for an
 101 attribute is a class. So this works:
 102
 103   has 'birth_date' => (
 104       is  => 'rw',
 105       isa => 'DateTime',
 106   );
 107
 108 In general, when Moose is presented with an unknown name, it assumes
 109 that the name is a class:
 110
 111   subtype 'ModernDateTime'
 112       => as 'DateTime'
 113       => where { $_->year() >= 1980 }
 114       => message { 'The date you provided is not modern enough' };
 115
 116   has 'valid_dates' => (
 117       is  => 'ro',
 118       isa => 'ArrayRef[DateTime]',
 119   );
 120
 121 Moose will assume that C<DateTime> is a class name in both of these
 122 instances.
 123
 124 =head1 SUBTYPES
 125
 126 Moose uses subtypes in its built-in hierarchy. C<Int> is a child of
 127 C<Num> for example.
 128
 129 A subtype is defined in terms of a parent type and a constraint. Any
 130 constraints defined by the parent(s) will be checked first, and then
 131 the the subtype's. A value must pass I<all> of these checks to be
 132 valid for the subtype.
 133
 134 Typically, a subtype takes the parent's constraint and makes it more
 135 specific.
 136
 137 A subtype can also define its own constraint failure message. This
 138 lets you do things like have an error "The value you provided (20),
 139 was not a valid rating, which must be a number from 1-10." This is
 140 much friendlier than the default error, which just says that the value
 141 failed a validation check for the type.
 142
 143 Here's a simple (and useful) subtype example:
 144
 145   subtype 'PositiveInt'
 146       => as 'Int'
 147       => where { $_ > 0 }
 148       => message { "The number you provided, $_, was not a positive number" }
 149
 150 Note that the sugar functions for working with types are all exported
 151 by L<Moose::Util::TypeConstraints>.
 152
 153 =head2 Creating a new type (that isn't a subtype)
 154
 155 You can also create new top-level types:
 156
 157   type 'FourCharacters' => where { defined $_ && length $_ == 4 };
 158
 159 In practice, this example is more or less the same as subtyping
 160 C<Str>, except you have to check definedness yourself.
 161
 162 It's hard to find a case where you wouldn't want to subtype a very
 163 broad type like C<Defined>, C<Ref> or C<Object>.
 164
 165 Defining a new top-level type is conceptually the same as subtyping
 166 C<Item>.
 167
 168 =head1 TYPE NAMES
 169
 170 Type names are global throughout the current Perl
 171 interpreter. Internally, Moose maps names to type objects via a
 172 L<registry|Moose::Meta::TypeConstraint::Registry>.
 173
 174 If you have multiple apps or libraries all using Moose in the same
 175 process, you could have problems with collisions. We recommend that
 176 you prefix names with some sort of namespace indicator to prevent
 177 these sorts of collisions.
 178
 179 For example, instead of calling a type "PositiveInt", call it
 180 "MyApp.Type.PositiveInt".
 181
 182 Type names are just strings. We recommend that you I<do not> use "::"
 183 as a separator in type names. This can be very confusing, because
 184 class names are I<also> valid type names! Using something else, like a
 185 period, makes it clear that "MyApp::User" is a class and
 186 "MyApp.Type.PositiveInt" is a Moose type defined by your application.
 187
 188 The L<MooseX::Types> module lets you create bareword aliases to longer
 189 names and also automatically namespaces all the types you define.
 190
 191 =head1 COERCION
 192
 193 One of the most powerful features of Moose's type system is its
 194 coercions. A coercion is a way to convert from one type to another.
 195
 196   subtype 'ArrayRefOfInts'
 197       => as 'ArrayRef[Int]';
 198
 199   coerce 'ArrayRefOfInts'
 200       => from 'Int'
 201       => via { [ $_ ] };
 202
 203 You'll note that we had to create a subtype rather than coercing
 204 C<ArrayRef[Int]> directly. This is just a quirk of how Moose
 205 works.
 206
 207 Coercions, like type names, are global. This is I<another> reason why
 208 it is good to namespace your types. Moose will I<never> try to coerce
 209 a value unless you explicitly ask for it. This is done by setting the
 210 C<coerce> attribute parameter to a true value:
 211
 212   package Foo;
 213
 214   has 'sizes' => (
 215       is     => 'rw',
 216       isa    => 'ArrayRefOfInts',
 217       coerce => 1,
 218   );
 219
 220   Foo->new( sizes => 42 );
 221
 222 This code example will do the right thing, and the newly created
 223 object will have C<[ 42 ]> as its C<sizes> attribute.
 224
 225 =head2 Deep coercion
 226
 227 Deep coercion is the coercion of type parameters for parameterized
 228 types. Let's take these types as an example:
 229
 230   subtype 'HexNum'
 231       => as 'Str'
 232       => where { /[a-f0-9]/i };
 233
 234   coerce 'Int'
 235       => from 'HexNum'
 236       => via { hex $_ };
 237
 238   has 'sizes' => (
 239       is     => 'rw',
 240       isa    => 'ArrayRef[Int]',
 241       coerce => 1,
 242   );
 243
 244 If we try passing an array reference of hex numbers for the C<sizes>
 245 attribute, Moose will not do any coercion.
 246
 247 However, you can define a set of subtypes to enable coercion between
 248 two parameterized types.
 249
 250   subtype 'ArrayRefOfHexNums'
 251       => as 'ArrayRef[HexNum]';
 252
 253   subtype 'ArrayRefOfInts'
 254       => as 'ArrayRef[Int]';
 255
 256   coerce 'ArrayRefOfInts'
 257       => from 'ArrayRefOfHexNums'
 258       => via { [ map { hex } @{$_} ] };
 259
 260   Foo->new( sizes => [ 'a1', 'ff', '22' ] );
 261
 262 Now Moose will coerce the hex numbers to integers.
 263
 264 However, Moose does not attempt to chain coercions, so it will not
 265 coerce a single hex number. To do that, we need to define a separate
 266 coercion:
 267
 268   coerce 'ArrayRefOfInts'
 269       => from 'HexNum'
 270       => via { [ hex $_ ] };
 271
 272 Yes, this can all get verbose, but coercion is tricky magic, and we
 273 think it's best to make it explicit.
 274
 275 =head1 TYPE UNIONS
 276
 277 Moose allows you to say that an attribute can be of two or more
 278 disparate types. For example, we might allow an C<Object> or
 279 C<FileHandle>:
 280
 281   has 'output' => (
 282       is  => 'rw',
 283       isa => 'Object | FileHandle',
 284   );
 285
 286 Moose actually parses that string and recognizes that you are creating
 287 a type union. The C<output> attribute will accept any sort of object,
 288 as well as an unblessed file handle. It is up to you to do the right
 289 thing for each of them in your code.
 290
 291 Whenever you use a type union, you should consider whether or not
 292 coercion might be a better answer.
 293
 294 For our example above, we might want to be more specific, and insist
 295 that output be an object with a C<print> method:
 296
 297   subtype 'CanPrint'
 298       => as 'Object'
 299       => where { $_->can('print') };
 300
 301 We can coerce file handles to an object that satisfies this condition
 302 with a simple wrapper class:
 303
 304   package FHWrapper;
 305
 306   use Moose;
 307
 308   has 'handle' => (
 309       is  => 'ro',
 310       isa => 'FileHandle',
 311   );
 312
 313   sub print {
 314       my $self = shift;
 315       my $fh   = $self->handle();
 316
 317       print $fh @_;
 318   }
 319
 320 Now we can define a coercion from C<FileHandle> to our wrapper class:
 321
 322   coerce 'CanPrint'
 323       => from 'FileHandle'
 324       => via { FHWrapper->new( handle => $_ ) };
 325
 326   has 'output' => (
 327       is     => 'rw',
 328       isa    => 'CanPrint',
 329       coerce => 1,
 330   );
 331
 332 This pattern of using a coercion instead of a type union will help
 333 make your class internals simpler.
 334
 335 =head1 TYPE CREATION HELPERS
 336
 337 The L<Moose::Util::TypeConstraints> module exports a number of helper
 338 functions for creating specific kinds of types. These include
 339 C<class_type>, C<role_type>, and C<maybe_type>. See the docs for
 340 details.
 341
 342 One helper worth noting is C<enum>, which allows you to create a
 343 subtype of C<Str> that only allows the specified values:
 344
 345   enum 'RGB' => qw( red green blue );
 346
 347 This creates a type named C<RGB>
 348
 349 =head1 ANONYMOUS TYPES
 350
 351 All of the type creation functions return a type object. This type
 352 object can be used wherever you would use a type name, as a parent
 353 type, or as the value for an attribute's C<isa> parameter:
 354
 355   has 'size' => (
 356       is => 'rw',
 357       isa => subtype 'Int' => where { $_ > 0 },
 358   );
 359
 360 This is handy when you want to create a one-off type and don't want to
 361 "pollute" the global namespace registry.
 362
 363 =head1 VALIDATING METHOD PARAMETERS
 364
 365 Moose does not provide any means of validating method
 366 parameters. However, there are several MooseX extensions on CPAN which
 367 let you do this.
 368
 369 The simplest and least sugary is L<MooseX::Params::Validate>. This
 370 lets you validate a set of named parameters using Moose types:
 371
 372   use Moose;
 373   use MooseX::Params::Validate;
 374
 375   sub foo {
 376       my $self   = shift;
 377       my %params = validated_hash(
 378           \@_,
 379           bar => { isa => 'Str', default => 'Moose' },
 380       );
 381       ...
 382   }
 383
 384 L<MooseX::Params::Validate> also supports coercions.
 385
 386 There are several more powerful extensions that support method
 387 parameter validation using Moose types, including
 388 L<MooseX::Method::Signatures>, which gives you a full-blown C<method>
 389 keyword.
 390
 391   method morning (Str $name) {
 392       $self->say("Good morning ${name}!");
 393   }
 394
 395 =head1 LOAD ORDER ISSUES
 396
 397 Because Moose types are defined at runtime, you may run into load
 398 order problems. In particular, you may want to use a class's type
 399 constraint before that type has been defined.
 400
 401 We have several recommendations for ameliorating this problem. First,
 402 define I<all> of your custom types in one module,
 403 C<MyApp::Types>. Second, load this module in all of your other
 404 modules.
 405
 406 If you are still having load order problems, you can make use of the
 407 C<find_type_constraint> function exported by
 408 L<Moose::Util::TypeConstraints>:
 409
 410   class_type('MyApp::User')
 411       unless find_type_constraint('MyApp::User') || ;
 412
 413 This sort of "find or create" logic is simple to write, and will let
 414 you work around load order issues.
 415
 416 =head1 AUTHOR
 417
 418 Dave Rolsky E<lt>autarch@urth.orgE<gt>
 419
 420 =head1 COPYRIGHT AND LICENSE
 421
 422 Copyright 2009 by Infinity Interactive, Inc.
 423
 424 L<http://www.iinteractive.com>
 425
 426 This library is free software; you can redistribute it and/or modify
 427 it under the same terms as Perl itself.
 428
 429 =cut