lib/MooseX/Types.pm

   1 package MooseX::Types;
   2 use Moose;
   3
   4 # ABSTRACT: Organise your Moose types in libraries
   5
   6 use Moose::Util::TypeConstraints;
   7 use MooseX::Types::TypeDecorator;
   8 use MooseX::Types::Base               ();
   9 use MooseX::Types::Util               qw( filter_tags );
  10 use MooseX::Types::UndefinedType;
  11 use MooseX::Types::CheckedUtilExports ();
  12 use Carp::Clan                        qw( ^MooseX::Types );
  13 use Sub::Name;
  14 use Scalar::Util                      'reftype';
  15
  16 use namespace::autoclean;
  17
  18 use 5.008;
  19 my $UndefMsg = q{Action for type '%s' not yet defined in library '%s'};
  20
  21 =pod
  22
  23 =head1 SYNOPSIS
  24
  25 =head2 Library Definition
  26
  27   package MyLibrary;
  28
  29   # predeclare our own types
  30   use MooseX::Types -declare => [
  31       qw(
  32           PositiveInt
  33           NegativeInt
  34           ArrayRefOfPositiveInt
  35           ArrayRefOfAtLeastThreeNegativeInts
  36           LotsOfInnerConstraints
  37           StrOrArrayRef
  38           MyDateTime
  39           )
  40   ];
  41
  42   # import builtin types
  43   use MooseX::Types::Moose qw/Int HashRef/;
  44
  45   # type definition.
  46   subtype PositiveInt,
  47       as Int,
  48       where { $_ > 0 },
  49       message { "Int is not larger than 0" };
  50
  51   subtype NegativeInt,
  52       as Int,
  53       where { $_ < 0 },
  54       message { "Int is not smaller than 0" };
  55
  56   # type coercion
  57   coerce PositiveInt,
  58       from Int,
  59           via { 1 };
  60
  61   # with parameterized constraints.
  62
  63   subtype ArrayRefOfPositiveInt,
  64     as ArrayRef[PositiveInt];
  65
  66   subtype ArrayRefOfAtLeastThreeNegativeInts,
  67     as ArrayRef[NegativeInt],
  68     where { scalar(@$_) > 2 };
  69
  70   subtype LotsOfInnerConstraints,
  71     as ArrayRef[ArrayRef[HashRef[Int]]];
  72
  73   # with TypeConstraint Unions
  74
  75   subtype StrOrArrayRef,
  76     as Str|ArrayRef;
  77
  78   # class types
  79
  80   class_type 'DateTime';
  81
  82   # or better
  83
  84   class_type MyDateTime, { class => 'DateTime' };
  85
  86   coerce MyDateTime,
  87     from HashRef,
  88     via { DateTime->new(%$_) };
  89
  90   1;
  91
  92 =head2 Usage
  93
  94   package Foo;
  95   use Moose;
  96   use MyLibrary qw( PositiveInt NegativeInt );
  97
  98   # use the exported constants as type names
  99   has 'bar',
 100       isa    => PositiveInt,
 101       is     => 'rw';
 102   has 'baz',
 103       isa    => NegativeInt,
 104       is     => 'rw';
 105
 106   sub quux {
 107       my ($self, $value);
 108
 109       # test the value
 110       print "positive\n" if is_PositiveInt($value);
 111       print "negative\n" if is_NegativeInt($value);
 112
 113       # coerce the value, NegativeInt doesn't have a coercion
 114       # helper, since it didn't define any coercions.
 115       $value = to_PositiveInt($value) or die "Cannot coerce";
 116   }
 117
 118   1;
 119
 120 =head1 DESCRIPTION
 121
 122 The type system provided by Moose effectively makes all of its builtin type
 123 global, as are any types you declare with Moose. This means that every module
 124 that declares a type named C<PositiveInt> is sharing the same type object. This
 125 can be a problem when different parts of the code base want to use the same
 126 name for different things.
 127
 128 This package lets you declare types using short names, but behind the scenes
 129 it namespaces all your type declarations, effectively prevent name clashes
 130 between packages.
 131
 132 This is done by creating a type library module like C<MyApp::Types> and then
 133 importing types from that module into other modules.
 134
 135 As a side effect, the declaration mechanism allows you to write type names as
 136 barewords (really function calls), which catches typos in names at compile
 137 time rather than run time.
 138
 139 This module also provides some helper functions for using Moose types outside
 140 of attribute declarations.
 141
 142 If you mix string-based names with types created by this module, it will warn,
 143 with a few exceptions. If you are declaring a C<class_type()> or
 144 C<role_type()> within your type library, or if you use a fully qualified name
 145 like C<"MyApp::Foo">.
 146
 147 =head1 LIBRARY DEFINITION
 148
 149 A MooseX::Types is just a normal Perl module. Unlike Moose
 150 itself, it does not install C<use strict> and C<use warnings> in your
 151 class by default, so this is up to you.
 152
 153 The only thing a library is required to do is
 154
 155   use MooseX::Types -declare => \@types;
 156
 157 with C<@types> being a list of types you wish to define in this library.
 158 This line will install a proper base class in your package as well as the
 159 full set of L<handlers|/"TYPE HANDLER FUNCTIONS"> for your declared
 160 types. It will then hand control over to L<Moose::Util::TypeConstraints>'
 161 C<import> method to export the functions you will need to declare your
 162 types.
 163
 164 If you want to use Moose' built-in types (e.g. for subtyping) you will
 165 want to
 166
 167   use MooseX::Types::Moose @types;
 168
 169 to import the helpers from the shipped L<MooseX::Types::Moose>
 170 library which can export all types that come with Moose.
 171
 172 You will have to define coercions for your types or your library won't
 173 export a L</to_$type> coercion helper for it.
 174
 175 Note that you currently cannot define types containing C<::>, since
 176 exporting would be a problem.
 177
 178 You also don't need to use C<warnings> and C<strict>, since the
 179 definition of a library automatically exports those.
 180
 181 =head1 LIBRARY USAGE
 182
 183 You can import the L<"type helpers"|/"TYPE HANDLER FUNCTIONS"> of a
 184 library by C<use>ing it with a list of types to import as arguments. If
 185 you want all of them, use the C<:all> tag. For example:
 186
 187   use MyLibrary      ':all';
 188   use MyOtherLibrary qw( TypeA TypeB );
 189
 190 MooseX::Types comes with a library of Moose' built-in types called
 191 L<MooseX::Types::Moose>.
 192
 193 The exporting mechanism is, since version 0.5, implemented via a wrapper
 194 around L<Sub::Exporter>. This means you can do something like this:
 195
 196   use MyLibrary TypeA => { -as => 'MyTypeA' },
 197                 TypeB => { -as => 'MyTypeB' };
 198
 199 =head1 TYPE HANDLER FUNCTIONS
 200
 201 =head2 $type
 202
 203 A constant with the name of your type. It contains the type's fully
 204 qualified name. Takes no value, as all constants.
 205
 206 =head2 is_$type
 207
 208 This handler takes a value and tests if it is a valid value for this
 209 C<$type>. It will return true or false.
 210
 211 =head2 to_$type
 212
 213 A handler that will take a value and coerce it into the C<$type>. It will
 214 return a false value if the type could not be coerced.
 215
 216 B<Important Note>: This handler will only be exported for types that can
 217 do type coercion. This has the advantage that a coercion to a type that
 218 has not defined any coercions will lead to a compile-time error.
 219
 220 =head1 WRAPPING A LIBRARY
 221
 222 You can define your own wrapper subclasses to manipulate the behaviour
 223 of a set of library exports. Here is an example:
 224
 225   package MyWrapper;
 226   use strict;
 227   use MRO::Compat;
 228   use base 'MooseX::Types::Wrapper';
 229
 230   sub coercion_export_generator {
 231       my $class = shift;
 232       my $code = $class->next::method(@_);
 233       return sub {
 234           my $value = $code->(@_);
 235           warn "Coercion returned undef!"
 236               unless defined $value;
 237           return $value;
 238       };
 239   }
 240
 241   1;
 242
 243 This class wraps the coercion generator (e.g., C<to_Int()>) and warns
 244 if a coercion returned an undefined value. You can wrap any library
 245 with this:
 246
 247   package Foo;
 248   use strict;
 249   use MyWrapper MyLibrary => [qw( Foo Bar )],
 250                 Moose     => [qw( Str Int )];
 251
 252   ...
 253   1;
 254
 255 The C<Moose> library name is a special shortcut for L<MooseX::Types::Moose>.
 256
 257 =head2 Generator methods you can overload
 258
 259 =over 4
 260
 261 =item type_export_generator( $short, $full )
 262
 263 Creates a closure returning the type's L<Moose::Meta::TypeConstraint> object.
 264
 265 =item check_export_generator( $short, $full, $undef_message )
 266
 267 This creates the closure used to test if a value is valid for this type.
 268
 269 =item coercion_export_generator( $short, $full, $undef_message )
 270
 271 This is the closure that's doing coercions.
 272
 273 =back
 274
 275 =head2 Provided Parameters
 276
 277 =over 4
 278
 279 =item $short
 280
 281 The short, exported name of the type.
 282
 283 =item $full
 284
 285 The fully qualified name of this type as L<Moose> knows it.
 286
 287 =item $undef_message
 288
 289 A message that will be thrown when type functionality is used but the
 290 type does not yet exist.
 291
 292 =back
 293
 294 =head1 RECURSIVE SUBTYPES
 295
 296 As of version 0.08, L<Moose::Types> has experimental support for Recursive
 297 subtypes.  This will allow:
 298
 299     subtype Tree() => as HashRef[Str|Tree];
 300
 301 Which validates things like:
 302
 303     {key=>'value'};
 304     {key=>{subkey1=>'value', subkey2=>'value'}}
 305
 306 And so on.  This feature is new and there may be lurking bugs so don't be afraid
 307 to hunt me down with patches and test cases if you have trouble.
 308
 309 =head1 NOTES REGARDING TYPE UNIONS
 310
 311 L<MooseX::Types> uses L<MooseX::Types::TypeDecorator> to do some overloading
 312 which generally allows you to easily create union types:
 313
 314   subtype StrOrArrayRef,
 315       as Str|ArrayRef;
 316
 317 As with parameterized constraints, this overloading extends to modules using the
 318 types you define in a type library.
 319
 320   use Moose;
 321   use MooseX::Types::Moose qw(HashRef Int);
 322
 323   has 'attr' => ( isa => HashRef | Int );
 324
 325 And everything should just work as you'd think.
 326
 327 =head1 METHODS
 328
 329 =head2 import
 330
 331 Installs the L<MooseX::Types::Base> class into the caller and exports types
 332 according to the specification described in L</"LIBRARY DEFINITION">. This
 333 will continue to L<Moose::Util::TypeConstraints>' C<import> method to export
 334 helper functions you will need to declare your types.
 335
 336 =cut
 337
 338 sub import {
 339     my ($class, %args) = @_;
 340     my  $caller = caller;
 341
 342     # everyone should want this
 343     strict->import;
 344     warnings->import;
 345
 346     # inject base class into new library
 347     {   no strict 'refs';
 348         unshift @{ $caller . '::ISA' }, 'MooseX::Types::Base';
 349     }
 350
 351     # generate predeclared type helpers
 352     if (my @orig_declare = @{ $args{ -declare } || [] }) {
 353         my ($tags, $declare) = filter_tags @orig_declare;
 354         my @to_export;
 355
 356         for my $type (@$declare) {
 357
 358             croak "Cannot create a type containing '::' ($type) at the moment"
 359                 if $type =~ /::/;
 360
 361             # add type to library and remember to export
 362             $caller->add_type($type);
 363             push @to_export, $type;
 364         }
 365
 366         $caller->import({ -full => 1, -into => $caller }, @to_export);
 367     }
 368
 369     # run type constraints import
 370     Moose::Util::TypeConstraints->import({ into => $caller });
 371
 372     # override some with versions that check for syntax errors
 373     MooseX::Types::CheckedUtilExports->import({ into => $caller });
 374
 375     1;
 376 }
 377
 378 =head2 type_export_generator
 379
 380 Generate a type export, e.g. C<Int()>. This will return either a
 381 L<Moose::Meta::TypeConstraint> object, or alternatively a
 382 L<MooseX::Types::UndefinedType> object if the type was not yet defined.
 383
 384 =cut
 385
 386 sub type_export_generator {
 387     my ($class, $type, $name) = @_;
 388
 389     ## Return an anonymous subroutine that will generate the proxied type
 390     ## constraint for you.
 391
 392     return subname "__TYPE__::$name" => sub {
 393         my $type_constraint = $class->create_base_type_constraint($name);
 394
 395         if(defined(my $params = shift @_)) {
 396             ## We currently only allow a TC to accept a single, ArrayRef
 397             ## parameter, as in HashRef[Int], where [Int] is what's inside the
 398             ## ArrayRef passed.
 399             if(reftype $params eq 'ARRAY') {
 400                 $type_constraint = $class->create_arged_type_constraint($name, @$params);
 401             } elsif(!defined $type_constraint) {
 402                 croak "Syntax error in type definition (did you forget a comma"
 403                     . " after $type?)";
 404             } else {
 405                 croak "Argument must be an ArrayRef to create a parameterized "
 406                     . "type, Eg.: ${type}[Int]. Got: ".ref($params)."."
 407             }
 408         }
 409
 410         $type_constraint = defined($type_constraint) ? $type_constraint
 411          : MooseX::Types::UndefinedType->new($name);
 412
 413         my $type_decorator = $class->create_type_decorator($type_constraint);
 414
 415         ## If there are additional args, that means it's probably stuff that
 416         ## needs to be returned to the subtype.  Not an ideal solution here but
 417         ## doesn't seem to cause trouble.
 418
 419         if(@_) {
 420             return ($type_decorator, @_);
 421         } else {
 422             return $type_decorator;
 423         }
 424     };
 425 }
 426
 427 =head2 create_arged_type_constraint ($name, @args)
 428
 429 Given a String $name with @args find the matching type constraint and parameterize
 430 it with @args.
 431
 432 =cut
 433
 434 sub create_arged_type_constraint {
 435     my ($class, $name, @args) = @_;
 436     my $type_constraint = Moose::Util::TypeConstraints::find_or_create_type_constraint("$name");
 437     my $parameterized = $type_constraint->parameterize(@args);
 438     # It's obnoxious to have to parameterize before looking for the TC, but the
 439     # alternative is to hard-code the assumption that the name is
 440     # "$name[$args[0]]", which would be worse.
 441     # This breaks MXMS, unfortunately, which relies on things like Tuple[...]
 442     # creating new type objects each time.
 443     # if (my $existing =
 444     #     Moose::Util::TypeConstraints::find_type_constraint($parameterized->name)) {
 445     #     return $existing;
 446     # }
 447     # Moose::Util::TypeConstraints::register_type_constraint($parameterized);
 448     return $parameterized;
 449 }
 450
 451 =head2 create_base_type_constraint ($name)
 452
 453 Given a String $name, find the matching type constraint.
 454
 455 =cut
 456
 457 sub create_base_type_constraint {
 458     my ($class, $name) = @_;
 459     return find_type_constraint($name);
 460 }
 461
 462 =head2 create_type_decorator ($type_constraint)
 463
 464 Given a $type_constraint, return a lightweight L<MooseX::Types::TypeDecorator>
 465 instance.
 466
 467 =cut
 468
 469 sub create_type_decorator {
 470     my ($class, $type_constraint) = @_;
 471     return MooseX::Types::TypeDecorator->new($type_constraint);
 472 }
 473
 474 =head2 coercion_export_generator
 475
 476 This generates a coercion handler function, e.g. C<to_Int($value)>.
 477
 478 =cut
 479
 480 sub coercion_export_generator {
 481     my ($class, $type, $full, $undef_msg) = @_;
 482     return sub {
 483         my ($value) = @_;
 484
 485         # we need a type object
 486         my $tobj = find_type_constraint($full) or croak $undef_msg;
 487         my $return = $tobj->coerce($value);
 488
 489         # non-successful coercion returns false
 490         return unless $tobj->check($return);
 491
 492         return $return;
 493     }
 494 }
 495
 496 =head2 check_export_generator
 497
 498 Generates a constraint check closure, e.g. C<is_Int($value)>.
 499
 500 =cut
 501
 502 sub check_export_generator {
 503     my ($class, $type, $full, $undef_msg) = @_;
 504     return sub {
 505         my ($value) = @_;
 506
 507         # we need a type object
 508         my $tobj = find_type_constraint($full) or croak $undef_msg;
 509
 510         return $tobj->check($value);
 511     }
 512 }
 513
 514 =head1 CAVEATS
 515
 516 The following are lists of gotchas and their workarounds for developers coming
 517 from the standard string based type constraint names
 518
 519 =head2 Uniqueness
 520
 521 A library makes the types quasi-unique by prefixing their names with (by
 522 default) the library package name. If you're only using the type handler
 523 functions provided by MooseX::Types, you shouldn't ever have to use
 524 a type's actual full name.
 525
 526 =head2 Argument separation ('=>' versus ',')
 527
 528 The L<perlop> manpage has this to say about the '=>' operator: "The => operator is
 529 a synonym for the comma, but forces any word (consisting entirely of word
 530 characters) to its left to be interpreted as a string (as of 5.001). This
 531 includes words that might otherwise be considered a constant or function call."
 532
 533 Due to this stringification, the following will NOT work as you might think:
 534
 535   subtype StrOrArrayRef => as Str | ArrayRef;
 536
 537 The C<StrOrArrayRef> type will have its stringification activated -- this causes the
 538 subtype to not be created.  Since the bareword type constraints are not strings
 539 you really should not try to treat them that way.  You will have to use the ','
 540 operator instead.  The authors of this package realize that all the L<Moose>
 541 documentation and examples nearly uniformly use the '=>' version of the comma
 542 operator and this could be an issue if you are converting code.
 543
 544 Patches welcome for discussion.
 545
 546 =head2 Compatibility with Sub::Exporter
 547
 548 If you want to use L<Sub::Exporter> with a Type Library, you need to make sure
 549 you export all the type constraints declared AS WELL AS any additional export
 550 targets. For example if you do:
 551
 552   package TypeAndSubExporter;
 553
 554   use MooseX::Types::Moose qw(Str);
 555   use MooseX::Types -declare => [qw(MyStr)];
 556   use Sub::Exporter -setup => { exports => [qw(something)] };
 557
 558   subtype MyStr, as Str;
 559
 560   sub something {
 561       return 1;
 562   }
 563
 564   # then in another module ...
 565
 566   package Foo;
 567   use TypeAndSubExporter qw(MyStr);
 568
 569 You'll get a C<< "MyStr" is not exported by the TypeAndSubExporter module >> error.
 570 It can be worked around by:
 571
 572   - use Sub::Exporter -setup => { exports => [ qw(something) ] };
 573   + use Sub::Exporter -setup => { exports => [ qw(something MyStr) ] };
 574
 575 This is a workaround and I am exploring how to make these modules work better
 576 together.  I realize this workaround will lead a lot of duplication in your
 577 export declarations and will be onerous for large type libraries.  Patches and
 578 detailed test cases welcome. See the tests directory for a start on this.
 579
 580 =head1 COMBINING TYPE LIBRARIES
 581
 582 You may want to combine a set of types for your application with other type
 583 libraries, like L<MooseX::Types::Moose> or L<MooseX::Types::Common::String>.
 584
 585 The L<MooseX::Types::Combine> module provides a simple API for combining a set
 586 of type libraries together.
 587
 588 =head1 SEE ALSO
 589
 590 L<Moose>, L<Moose::Util::TypeConstraints>, L<MooseX::Types::Moose>,
 591 L<Sub::Exporter>
 592
 593 =head1 ACKNOWLEDGEMENTS
 594
 595 Many thanks to the C<#moose> cabal on C<irc.perl.org>.
 596
 597 =cut