6 MooseX::Types - Organise your Moose types in libraries
10 use Moose::Util::TypeConstraints;
11 use MooseX::Types::TypeDecorator;
12 use MooseX::Types::Base ();
13 use MooseX::Types::Util qw( filter_tags );
14 use MooseX::Types::UndefinedType;
15 use MooseX::Types::CheckedUtilExports ();
16 use Carp::Clan qw( ^MooseX::Types );
18 use Scalar::Util 'reftype';
20 use namespace::clean -except => [qw( meta )];
23 our $VERSION = '0.15';
24 my $UndefMsg = q{Action for type '%s' not yet defined in library '%s'};
28 =head2 Library Definition
32 # predeclare our own types
35 PositiveInt NegativeInt
36 ArrayRefOfPositiveInt ArrayRefOfAtLeastThreeNegativeInts
37 LotsOfInnerConstraints StrOrArrayRef
40 # import builtin types
41 use MooseX::Types::Moose qw/Int HashRef/;
47 message { "Int is not larger than 0" };
52 message { "Int is not smaller than 0" };
59 # with parameterized constraints.
61 subtype ArrayRefOfPositiveInt,
62 as ArrayRef[PositiveInt];
64 subtype ArrayRefOfAtLeastThreeNegativeInts,
65 as ArrayRef[NegativeInt],
66 where { scalar(@$_) > 2 };
68 subtype LotsOfInnerConstraints,
69 as ArrayRef[ArrayRef[HashRef[Int]]];
71 # with TypeConstraint Unions
73 subtype StrOrArrayRef,
76 class_type 'DateTime';
80 via { DateTime->new(%$_) };
88 use MyLibrary qw( PositiveInt NegativeInt );
90 # use the exported constants as type names
102 print "positive\n" if is_PositiveInt($value);
103 print "negative\n" if is_NegativeInt($value);
105 # coerce the value, NegativeInt doesn't have a coercion
106 # helper, since it didn't define any coercions.
107 $value = to_PositiveInt($value) or die "Cannot coerce";
114 The types provided with L<Moose> are by design global. This package helps
115 you to organise and selectively import your own and the built-in types in
116 libraries. As a nice side effect, it catches typos at compile-time too.
118 However, the main reason for this module is to provide an easy way to not
119 have conflicts with your type names, since the internal fully qualified
120 names of the types will be prefixed with the library's name.
122 This module will also provide you with some helper functions to make it
123 easier to use Moose types in your code.
125 String type names will produce a warning, unless it's for a C<class_type> or
126 C<role_type> declared within the library, or a fully qualified name like
127 C<'MyTypeLibrary::Foo'>.
129 =head1 TYPE HANDLER FUNCTIONS
133 A constant with the name of your type. It contains the type's fully
134 qualified name. Takes no value, as all constants.
138 This handler takes a value and tests if it is a valid value for this
139 C<$type>. It will return true or false.
143 A handler that will take a value and coerce it into the C<$type>. It will
144 return a false value if the type could not be coerced.
146 B<Important Note>: This handler will only be exported for types that can
147 do type coercion. This has the advantage that a coercion to a type that
148 cannot hasn't defined any coercions will lead to a compile-time error.
150 =head1 LIBRARY DEFINITION
152 A MooseX::Types is just a normal Perl module. Unlike Moose
153 itself, it does not install C<use strict> and C<use warnings> in your
154 class by default, so this is up to you.
156 The only thing a library is required to do is
158 use MooseX::Types -declare => \@types;
160 with C<@types> being a list of types you wish to define in this library.
161 This line will install a proper base class in your package as well as the
162 full set of L<handlers|/"TYPE HANDLER FUNCTIONS"> for your declared
163 types. It will then hand control over to L<Moose::Util::TypeConstraints>'
164 C<import> method to export the functions you will need to declare your
167 If you want to use Moose' built-in types (e.g. for subtyping) you will
170 use MooseX::Types::Moose @types;
172 to import the helpers from the shipped L<MooseX::Types::Moose>
173 library which can export all types that come with Moose.
175 You will have to define coercions for your types or your library won't
176 export a L</to_$type> coercion helper for it.
178 Note that you currently cannot define types containing C<::>, since
179 exporting would be a problem.
181 You also don't need to use C<warnings> and C<strict>, since the
182 definition of a library automatically exports those.
186 You can import the L<"type helpers"|/"TYPE HANDLER FUNCTIONS"> of a
187 library by C<use>ing it with a list of types to import as arguments. If
188 you want all of them, use the C<:all> tag. For example:
190 use MyLibrary ':all';
191 use MyOtherLibrary qw( TypeA TypeB );
193 MooseX::Types comes with a library of Moose' built-in types called
194 L<MooseX::Types::Moose>.
196 The exporting mechanism is, since version 0.5, implemented via a wrapper
197 around L<Sub::Exporter>. This means you can do something like this:
199 use MyLibrary TypeA => { -as => 'MyTypeA' },
200 TypeB => { -as => 'MyTypeB' };
202 =head1 WRAPPING A LIBRARY
204 You can define your own wrapper subclasses to manipulate the behaviour
205 of a set of library exports. Here is an example:
210 use base 'MooseX::Types::Wrapper';
212 sub coercion_export_generator {
214 my $code = $class->next::method(@_);
216 my $value = $code->(@_);
217 warn "Coercion returned undef!"
218 unless defined $value;
225 This class wraps the coercion generator (e.g., C<to_Int()>) and warns
226 if a coercion returned an undefined value. You can wrap any library
231 use MyWrapper MyLibrary => [qw( Foo Bar )],
232 Moose => [qw( Str Int )];
237 The C<Moose> library name is a special shortcut for
238 L<MooseX::Types::Moose>.
240 =head2 Generator methods you can overload
244 =item type_export_generator( $short, $full )
246 Creates a closure returning the type's L<Moose::Meta::TypeConstraint>
249 =item check_export_generator( $short, $full, $undef_message )
251 This creates the closure used to test if a value is valid for this type.
253 =item coercion_export_generator( $short, $full, $undef_message )
255 This is the closure that's doing coercions.
259 =head2 Provided Parameters
265 The short, exported name of the type.
269 The fully qualified name of this type as L<Moose> knows it.
273 A message that will be thrown when type functionality is used but the
274 type does not yet exist.
278 =head1 RECURSIVE SUBTYPES
280 As of version 0.08, L<Moose::Types> has experimental support for Recursive
281 subtypes. This will allow:
283 subtype Tree() => as HashRef[Str|Tree];
285 Which validates things like:
288 {key=>{subkey1=>'value', subkey2=>'value'}}
290 And so on. This feature is new and there may be lurking bugs so don't be afraid
291 to hunt me down with patches and test cases if you have trouble.
293 =head1 NOTES REGARDING TYPE UNIONS
295 L<MooseX::Types> uses L<MooseX::Types::TypeDecorator> to do some overloading
296 which generally allows you to easily create union types:
298 subtype StrOrArrayRef,
301 As with parameterized constrains, this overloading extends to modules using the
302 types you define in a type library.
305 use MooseX::Types::Moose qw(HashRef Int);
307 has 'attr' => (isa=>HashRef|Int);
309 And everything should just work as you'd think.
315 Installs the L<MooseX::Types::Base> class into the caller and
316 exports types according to the specification described in
317 L</"LIBRARY DEFINITION">. This will continue to
318 L<Moose::Util::TypeConstraints>' C<import> method to export helper
319 functions you will need to declare your types.
324 my ($class, %args) = @_;
327 # everyone should want this
331 # inject base class into new library
333 unshift @{ $callee . '::ISA' }, 'MooseX::Types::Base';
336 # generate predeclared type helpers
337 if (my @orig_declare = @{ $args{ -declare } || [] }) {
338 my ($tags, $declare) = filter_tags @orig_declare;
341 for my $type (@$declare) {
343 croak "Cannot create a type containing '::' ($type) at the moment"
346 # add type to library and remember to export
347 $callee->add_type($type);
348 push @to_export, $type;
351 $callee->import({ -full => 1, -into => $callee }, @to_export);
354 # run type constraints import
355 Moose::Util::TypeConstraints->import({ into => $callee });
357 # override some with versions that check for syntax errors
358 MooseX::Types::CheckedUtilExports->import({ into => $callee });
363 =head2 type_export_generator
365 Generate a type export, e.g. C<Int()>. This will return either a
366 L<Moose::Meta::TypeConstraint> object, or alternatively a
367 L<MooseX::Types::UndefinedType> object if the type was not
372 sub type_export_generator {
373 my ($class, $type, $name) = @_;
375 ## Return an anonymous subroutine that will generate the proxied type
376 ## constraint for you.
378 return subname "__TYPE__::$name" => sub {
379 my $type_constraint = $class->create_base_type_constraint($name);
381 if(defined(my $params = shift @_)) {
382 ## We currently only allow a TC to accept a single, ArrayRef
383 ## parameter, as in HashRef[Int], where [Int] is what's inside the
385 if(reftype $params eq 'ARRAY') {
386 $type_constraint = $class->create_arged_type_constraint($name, @$params);
387 } elsif(!defined $type_constraint) {
388 croak "Syntax error in type definition (did you forget a comma"
391 croak "Argument must be an ArrayRef to create a parameterized "
392 . "type, Eg.: ${type}[Int]. Got: ".ref($params)."."
396 $type_constraint = defined($type_constraint) ? $type_constraint
397 : MooseX::Types::UndefinedType->new($name);
399 my $type_decorator = $class->create_type_decorator($type_constraint);
401 ## If there are additional args, that means it's probably stuff that
402 ## needs to be returned to the subtype. Not an ideal solution here but
403 ## doesn't seem to cause trouble.
406 return ($type_decorator, @_);
408 return $type_decorator;
413 =head2 create_arged_type_constraint ($name, @args)
415 Given a String $name with @args find the matching typeconstraint and parameterize
420 sub create_arged_type_constraint {
421 my ($class, $name, @args) = @_;
422 my $type_constraint = Moose::Util::TypeConstraints::find_or_create_type_constraint("$name");
423 return $type_constraint->parameterize(@args);
426 =head2 create_base_type_constraint ($name)
428 Given a String $name, find the matching typeconstraint.
432 sub create_base_type_constraint {
433 my ($class, $name) = @_;
434 return find_type_constraint($name);
437 =head2 create_type_decorator ($type_constraint)
439 Given a $type_constraint, return a lightweight L<MooseX::Types::TypeDecorator>
444 sub create_type_decorator {
445 my ($class, $type_constraint) = @_;
446 return MooseX::Types::TypeDecorator->new($type_constraint);
449 =head2 coercion_export_generator
451 This generates a coercion handler function, e.g. C<to_Int($value)>.
455 sub coercion_export_generator {
456 my ($class, $type, $full, $undef_msg) = @_;
460 # we need a type object
461 my $tobj = find_type_constraint($full) or croak $undef_msg;
462 my $return = $tobj->coerce($value);
464 # non-successful coercion returns false
465 return unless $tobj->check($return);
471 =head2 check_export_generator
473 Generates a constraint check closure, e.g. C<is_Int($value)>.
477 sub check_export_generator {
478 my ($class, $type, $full, $undef_msg) = @_;
482 # we need a type object
483 my $tobj = find_type_constraint($full) or croak $undef_msg;
485 return $tobj->check($value);
491 The following are lists of gotcha's and their workarounds for developers coming
492 from the standard string based type constraint names
496 A library makes the types quasi-unique by prefixing their names with (by
497 default) the library package name. If you're only using the type handler
498 functions provided by MooseX::Types, you shouldn't ever have to use
499 a type's actual full name.
501 =head2 Argument separation ('=>' versus ',')
503 The Perlop manpage has this to say about the '=>' operator: "The => operator is
504 a synonym for the comma, but forces any word (consisting entirely of word
505 characters) to its left to be interpreted as a string (as of 5.001). This
506 includes words that might otherwise be considered a constant or function call."
508 Due to this stringification, the following will NOT work as you might think:
510 subtype StrOrArrayRef => as Str|ArrayRef;
512 The 'StrOrArrayRef' will have it's stringification activated this causes the
513 subtype to not be created. Since the bareword type constraints are not strings
514 you really should not try to treat them that way. You will have to use the ','
515 operator instead. The author's of this package realize that all the L<Moose>
516 documention and examples nearly uniformly use the '=>' version of the comma
517 operator and this could be an issue if you are converting code.
519 Patches welcome for discussion.
521 =head2 Compatibility with Sub::Exporter
523 If you want to use L<Sub::Exporter> with a Type Library, you need to make sure
524 you export all the type constraints declared AS WELL AS any additional export
525 targets. For example if you do:
527 package TypeAndSubExporter; {
529 use MooseX::Types::Moose qw(Str);
530 use MooseX::Types -declare => [qw(MyStr)];
531 use Sub::Exporter -setup => { exports => [ qw(something) ] };
543 use TypeAndSubExporter qw(MyStr);
546 You'll get a '"MyStr" is not exported by the TypeAndSubExporter module' error.
547 Upi can workaround by:
549 - use Sub::Exporter -setup => { exports => [ qw(something) ] };
550 + use Sub::Exporter -setup => { exports => [ qw(something MyStr) ] };
552 This is a workaround and I am exploring how to make these modules work better
553 together. I realize this workaround will lead a lot of duplication in your
554 export declarations and will be onerous for large type libraries. Patches and
555 detailed test cases welcome. See the tests directory for a start on this.
560 L<Moose::Util::TypeConstraints>,
561 L<MooseX::Types::Moose>,
564 =head1 AUTHOR AND COPYRIGHT
566 Robert 'phaylon' Sedlacek C<E<lt>rs@474.atE<gt>>, with many thanks to
567 the C<#moose> cabal on C<irc.perl.org>.
569 Additional features by John Napiorkowski (jnapiorkowski) <jjnapiork@cpan.org>.
573 This program is free software; you can redistribute it and/or modify
574 it under the same terms as perl itself.