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.24';
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
41 # import builtin types
42 use MooseX::Types::Moose qw/Int HashRef/;
48 message { "Int is not larger than 0" };
53 message { "Int is not smaller than 0" };
60 # with parameterized constraints.
62 subtype ArrayRefOfPositiveInt,
63 as ArrayRef[PositiveInt];
65 subtype ArrayRefOfAtLeastThreeNegativeInts,
66 as ArrayRef[NegativeInt],
67 where { scalar(@$_) > 2 };
69 subtype LotsOfInnerConstraints,
70 as ArrayRef[ArrayRef[HashRef[Int]]];
72 # with TypeConstraint Unions
74 subtype StrOrArrayRef,
79 class_type 'DateTime';
83 class_type MyDateTime, { class => 'DateTime' };
87 via { DateTime->new(%$_) };
95 use MyLibrary qw( PositiveInt NegativeInt );
97 # use the exported constants as type names
109 print "positive\n" if is_PositiveInt($value);
110 print "negative\n" if is_NegativeInt($value);
112 # coerce the value, NegativeInt doesn't have a coercion
113 # helper, since it didn't define any coercions.
114 $value = to_PositiveInt($value) or die "Cannot coerce";
121 The types provided with L<Moose> are by design global. This package helps
122 you to organise and selectively import your own and the built-in types in
123 libraries. As a nice side effect, it catches typos at compile-time too.
125 However, the main reason for this module is to provide an easy way to not
126 have conflicts with your type names, since the internal fully qualified
127 names of the types will be prefixed with the library's name.
129 This module will also provide you with some helper functions to make it
130 easier to use Moose types in your code.
132 String type names will produce a warning, unless it's for a C<class_type> or
133 C<role_type> declared within the library, or a fully qualified name like
134 C<'MyTypeLibrary::Foo'>.
136 =head1 TYPE HANDLER FUNCTIONS
140 A constant with the name of your type. It contains the type's fully
141 qualified name. Takes no value, as all constants.
145 This handler takes a value and tests if it is a valid value for this
146 C<$type>. It will return true or false.
150 A handler that will take a value and coerce it into the C<$type>. It will
151 return a false value if the type could not be coerced.
153 B<Important Note>: This handler will only be exported for types that can
154 do type coercion. This has the advantage that a coercion to a type that
155 cannot hasn't defined any coercions will lead to a compile-time error.
157 =head1 LIBRARY DEFINITION
159 A MooseX::Types is just a normal Perl module. Unlike Moose
160 itself, it does not install C<use strict> and C<use warnings> in your
161 class by default, so this is up to you.
163 The only thing a library is required to do is
165 use MooseX::Types -declare => \@types;
167 with C<@types> being a list of types you wish to define in this library.
168 This line will install a proper base class in your package as well as the
169 full set of L<handlers|/"TYPE HANDLER FUNCTIONS"> for your declared
170 types. It will then hand control over to L<Moose::Util::TypeConstraints>'
171 C<import> method to export the functions you will need to declare your
174 If you want to use Moose' built-in types (e.g. for subtyping) you will
177 use MooseX::Types::Moose @types;
179 to import the helpers from the shipped L<MooseX::Types::Moose>
180 library which can export all types that come with Moose.
182 You will have to define coercions for your types or your library won't
183 export a L</to_$type> coercion helper for it.
185 Note that you currently cannot define types containing C<::>, since
186 exporting would be a problem.
188 You also don't need to use C<warnings> and C<strict>, since the
189 definition of a library automatically exports those.
193 You can import the L<"type helpers"|/"TYPE HANDLER FUNCTIONS"> of a
194 library by C<use>ing it with a list of types to import as arguments. If
195 you want all of them, use the C<:all> tag. For example:
197 use MyLibrary ':all';
198 use MyOtherLibrary qw( TypeA TypeB );
200 MooseX::Types comes with a library of Moose' built-in types called
201 L<MooseX::Types::Moose>.
203 The exporting mechanism is, since version 0.5, implemented via a wrapper
204 around L<Sub::Exporter>. This means you can do something like this:
206 use MyLibrary TypeA => { -as => 'MyTypeA' },
207 TypeB => { -as => 'MyTypeB' };
209 =head1 WRAPPING A LIBRARY
211 You can define your own wrapper subclasses to manipulate the behaviour
212 of a set of library exports. Here is an example:
217 use base 'MooseX::Types::Wrapper';
219 sub coercion_export_generator {
221 my $code = $class->next::method(@_);
223 my $value = $code->(@_);
224 warn "Coercion returned undef!"
225 unless defined $value;
232 This class wraps the coercion generator (e.g., C<to_Int()>) and warns
233 if a coercion returned an undefined value. You can wrap any library
238 use MyWrapper MyLibrary => [qw( Foo Bar )],
239 Moose => [qw( Str Int )];
244 The C<Moose> library name is a special shortcut for
245 L<MooseX::Types::Moose>.
247 =head2 Generator methods you can overload
251 =item type_export_generator( $short, $full )
253 Creates a closure returning the type's L<Moose::Meta::TypeConstraint>
256 =item check_export_generator( $short, $full, $undef_message )
258 This creates the closure used to test if a value is valid for this type.
260 =item coercion_export_generator( $short, $full, $undef_message )
262 This is the closure that's doing coercions.
266 =head2 Provided Parameters
272 The short, exported name of the type.
276 The fully qualified name of this type as L<Moose> knows it.
280 A message that will be thrown when type functionality is used but the
281 type does not yet exist.
285 =head1 RECURSIVE SUBTYPES
287 As of version 0.08, L<Moose::Types> has experimental support for Recursive
288 subtypes. This will allow:
290 subtype Tree() => as HashRef[Str|Tree];
292 Which validates things like:
295 {key=>{subkey1=>'value', subkey2=>'value'}}
297 And so on. This feature is new and there may be lurking bugs so don't be afraid
298 to hunt me down with patches and test cases if you have trouble.
300 =head1 NOTES REGARDING TYPE UNIONS
302 L<MooseX::Types> uses L<MooseX::Types::TypeDecorator> to do some overloading
303 which generally allows you to easily create union types:
305 subtype StrOrArrayRef,
308 As with parameterized constrains, this overloading extends to modules using the
309 types you define in a type library.
312 use MooseX::Types::Moose qw(HashRef Int);
314 has 'attr' => (isa=>HashRef|Int);
316 And everything should just work as you'd think.
322 Installs the L<MooseX::Types::Base> class into the caller and
323 exports types according to the specification described in
324 L</"LIBRARY DEFINITION">. This will continue to
325 L<Moose::Util::TypeConstraints>' C<import> method to export helper
326 functions you will need to declare your types.
331 my ($class, %args) = @_;
334 # everyone should want this
338 # inject base class into new library
340 unshift @{ $callee . '::ISA' }, 'MooseX::Types::Base';
343 # generate predeclared type helpers
344 if (my @orig_declare = @{ $args{ -declare } || [] }) {
345 my ($tags, $declare) = filter_tags @orig_declare;
348 for my $type (@$declare) {
350 croak "Cannot create a type containing '::' ($type) at the moment"
353 # add type to library and remember to export
354 $callee->add_type($type);
355 push @to_export, $type;
358 $callee->import({ -full => 1, -into => $callee }, @to_export);
361 # run type constraints import
362 Moose::Util::TypeConstraints->import({ into => $callee });
364 # override some with versions that check for syntax errors
365 MooseX::Types::CheckedUtilExports->import({ into => $callee });
370 =head2 type_export_generator
372 Generate a type export, e.g. C<Int()>. This will return either a
373 L<Moose::Meta::TypeConstraint> object, or alternatively a
374 L<MooseX::Types::UndefinedType> object if the type was not
379 sub type_export_generator {
380 my ($class, $type, $name) = @_;
382 ## Return an anonymous subroutine that will generate the proxied type
383 ## constraint for you.
385 return subname "__TYPE__::$name" => sub {
386 my $type_constraint = $class->create_base_type_constraint($name);
388 if(defined(my $params = shift @_)) {
389 ## We currently only allow a TC to accept a single, ArrayRef
390 ## parameter, as in HashRef[Int], where [Int] is what's inside the
392 if(reftype $params eq 'ARRAY') {
393 $type_constraint = $class->create_arged_type_constraint($name, @$params);
394 } elsif(!defined $type_constraint) {
395 croak "Syntax error in type definition (did you forget a comma"
398 croak "Argument must be an ArrayRef to create a parameterized "
399 . "type, Eg.: ${type}[Int]. Got: ".ref($params)."."
403 $type_constraint = defined($type_constraint) ? $type_constraint
404 : MooseX::Types::UndefinedType->new($name);
406 my $type_decorator = $class->create_type_decorator($type_constraint);
408 ## If there are additional args, that means it's probably stuff that
409 ## needs to be returned to the subtype. Not an ideal solution here but
410 ## doesn't seem to cause trouble.
413 return ($type_decorator, @_);
415 return $type_decorator;
420 =head2 create_arged_type_constraint ($name, @args)
422 Given a String $name with @args find the matching typeconstraint and parameterize
427 sub create_arged_type_constraint {
428 my ($class, $name, @args) = @_;
429 my $type_constraint = Moose::Util::TypeConstraints::find_or_create_type_constraint("$name");
430 my $parameterized = $type_constraint->parameterize(@args);
431 # It's obnoxious to have to parameterize before looking for the TC, but the
432 # alternative is to hard-code the assumption that the name is
433 # "$name[$args[0]]", which would be worse.
434 # This breaks MXMS, unfortunately, which relies on things like Tuple[...]
435 # creating new type objects each time.
437 # Moose::Util::TypeConstraints::find_type_constraint($parameterized->name)) {
440 # Moose::Util::TypeConstraints::register_type_constraint($parameterized);
441 return $parameterized;
444 =head2 create_base_type_constraint ($name)
446 Given a String $name, find the matching typeconstraint.
450 sub create_base_type_constraint {
451 my ($class, $name) = @_;
452 return find_type_constraint($name);
455 =head2 create_type_decorator ($type_constraint)
457 Given a $type_constraint, return a lightweight L<MooseX::Types::TypeDecorator>
462 sub create_type_decorator {
463 my ($class, $type_constraint) = @_;
464 return MooseX::Types::TypeDecorator->new($type_constraint);
467 =head2 coercion_export_generator
469 This generates a coercion handler function, e.g. C<to_Int($value)>.
473 sub coercion_export_generator {
474 my ($class, $type, $full, $undef_msg) = @_;
478 # we need a type object
479 my $tobj = find_type_constraint($full) or croak $undef_msg;
480 my $return = $tobj->coerce($value);
482 # non-successful coercion returns false
483 return unless $tobj->check($return);
489 =head2 check_export_generator
491 Generates a constraint check closure, e.g. C<is_Int($value)>.
495 sub check_export_generator {
496 my ($class, $type, $full, $undef_msg) = @_;
500 # we need a type object
501 my $tobj = find_type_constraint($full) or croak $undef_msg;
503 return $tobj->check($value);
509 The following are lists of gotcha's and their workarounds for developers coming
510 from the standard string based type constraint names
514 A library makes the types quasi-unique by prefixing their names with (by
515 default) the library package name. If you're only using the type handler
516 functions provided by MooseX::Types, you shouldn't ever have to use
517 a type's actual full name.
519 =head2 Argument separation ('=>' versus ',')
521 The Perlop manpage has this to say about the '=>' operator: "The => operator is
522 a synonym for the comma, but forces any word (consisting entirely of word
523 characters) to its left to be interpreted as a string (as of 5.001). This
524 includes words that might otherwise be considered a constant or function call."
526 Due to this stringification, the following will NOT work as you might think:
528 subtype StrOrArrayRef => as Str|ArrayRef;
530 The 'StrOrArrayRef' will have it's stringification activated this causes the
531 subtype to not be created. Since the bareword type constraints are not strings
532 you really should not try to treat them that way. You will have to use the ','
533 operator instead. The author's of this package realize that all the L<Moose>
534 documention and examples nearly uniformly use the '=>' version of the comma
535 operator and this could be an issue if you are converting code.
537 Patches welcome for discussion.
539 =head2 Compatibility with Sub::Exporter
541 If you want to use L<Sub::Exporter> with a Type Library, you need to make sure
542 you export all the type constraints declared AS WELL AS any additional export
543 targets. For example if you do:
545 package TypeAndSubExporter; {
547 use MooseX::Types::Moose qw(Str);
548 use MooseX::Types -declare => [qw(MyStr)];
549 use Sub::Exporter -setup => { exports => [ qw(something) ] };
561 use TypeAndSubExporter qw(MyStr);
564 You'll get a '"MyStr" is not exported by the TypeAndSubExporter module' error.
565 Upi can workaround by:
567 - use Sub::Exporter -setup => { exports => [ qw(something) ] };
568 + use Sub::Exporter -setup => { exports => [ qw(something MyStr) ] };
570 This is a workaround and I am exploring how to make these modules work better
571 together. I realize this workaround will lead a lot of duplication in your
572 export declarations and will be onerous for large type libraries. Patches and
573 detailed test cases welcome. See the tests directory for a start on this.
578 L<Moose::Util::TypeConstraints>,
579 L<MooseX::Types::Moose>,
582 =head1 ACKNOWLEDGEMENTS
584 Many thanks to the C<#moose> cabal on C<irc.perl.org>.
588 Robert "phaylon" Sedlacek <rs@474.at>
592 jnapiorkowski: John Napiorkowski <jjnapiork@cpan.org>
594 caelum: Rafael Kitover <rkitover@cpan.org>
596 rafl: Florian Ragwitz <rafl@debian.org>
598 hdp: Hans Dieter Pearcey <hdp@cpan.org>
600 autarch: Dave Rolsky <autarch@urth.org>
602 =head1 COPYRIGHT & LICENSE
604 Copyright (c) 2007-2009 Robert Sedlacek <rs@474.at>
606 This program is free software; you can redistribute it and/or modify
607 it under the same terms as perl itself.