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 Carp::Clan qw( ^MooseX::Types );
17 use namespace::clean -except => [qw( meta )];
20 our $VERSION = '0.10';
21 my $UndefMsg = q{Action for type '%s' not yet defined in library '%s'};
25 =head2 Library Definition
29 # predeclare our own types
32 PositiveInt NegativeInt
33 ArrayRefOfPositiveInt ArrayRefOfAtLeastThreeNegativeInts
34 LotsOfInnerConstraints StrOrArrayRef
37 # import builtin types
38 use MooseX::Types::Moose 'Int';
44 message { "Int is not larger than 0" };
49 message { "Int is not smaller than 0" };
56 # with parameterized constraints.
58 subtype ArrayRefOfPositiveInt,
59 as ArrayRef[PositiveInt];
61 subtype ArrayRefOfAtLeastThreeNegativeInts,
62 as ArrayRef[NegativeInt],
63 where { scalar(@$_) > 2 };
65 subtype LotsOfInnerConstraints,
66 as ArrayRef[ArrayRef[HashRef[Int]]];
68 # with TypeConstraint Unions
70 subtype StrOrArrayRef,
79 use MyLibrary qw( PositiveInt NegativeInt );
81 # use the exported constants as type names
93 print "positive\n" if is_PositiveInt($value);
94 print "negative\n" if is_NegativeInt($value);
96 # coerce the value, NegativeInt doesn't have a coercion
97 # helper, since it didn't define any coercions.
98 $value = to_PositiveInt($value) or die "Cannot coerce";
105 The types provided with L<Moose> are by design global. This package helps
106 you to organise and selectively import your own and the built-in types in
107 libraries. As a nice side effect, it catches typos at compile-time too.
109 However, the main reason for this module is to provide an easy way to not
110 have conflicts with your type names, since the internal fully qualified
111 names of the types will be prefixed with the library's name.
113 This module will also provide you with some helper functions to make it
114 easier to use Moose types in your code.
116 =head1 TYPE HANDLER FUNCTIONS
120 A constant with the name of your type. It contains the type's fully
121 qualified name. Takes no value, as all constants.
125 This handler takes a value and tests if it is a valid value for this
126 C<$type>. It will return true or false.
130 A handler that will take a value and coerce it into the C<$type>. It will
131 return a false value if the type could not be coerced.
133 B<Important Note>: This handler will only be exported for types that can
134 do type coercion. This has the advantage that a coercion to a type that
135 cannot hasn't defined any coercions will lead to a compile-time error.
137 =head1 LIBRARY DEFINITION
139 A MooseX::Types is just a normal Perl module. Unlike Moose
140 itself, it does not install C<use strict> and C<use warnings> in your
141 class by default, so this is up to you.
143 The only thing a library is required to do is
145 use MooseX::Types -declare => \@types;
147 with C<@types> being a list of types you wish to define in this library.
148 This line will install a proper base class in your package as well as the
149 full set of L<handlers|/"TYPE HANDLER FUNCTIONS"> for your declared
150 types. It will then hand control over to L<Moose::Util::TypeConstraints>'
151 C<import> method to export the functions you will need to declare your
154 If you want to use Moose' built-in types (e.g. for subtyping) you will
157 use MooseX::Types::Moose @types;
159 to import the helpers from the shipped L<MooseX::Types::Moose>
160 library which can export all types that come with Moose.
162 You will have to define coercions for your types or your library won't
163 export a L</to_$type> coercion helper for it.
165 Note that you currently cannot define types containing C<::>, since
166 exporting would be a problem.
168 You also don't need to use C<warnings> and C<strict>, since the
169 definition of a library automatically exports those.
173 You can import the L<"type helpers"|/"TYPE HANDLER FUNCTIONS"> of a
174 library by C<use>ing it with a list of types to import as arguments. If
175 you want all of them, use the C<:all> tag. For example:
177 use MyLibrary ':all';
178 use MyOtherLibrary qw( TypeA TypeB );
180 MooseX::Types comes with a library of Moose' built-in types called
181 L<MooseX::Types::Moose>.
183 The exporting mechanism is, since version 0.5, implemented via a wrapper
184 around L<Sub::Exporter>. This means you can do something like this:
186 use MyLibrary TypeA => { -as => 'MyTypeA' },
187 TypeB => { -as => 'MyTypeB' };
189 =head1 WRAPPING A LIBRARY
191 You can define your own wrapper subclasses to manipulate the behaviour
192 of a set of library exports. Here is an example:
197 use base 'MooseX::Types::Wrapper';
199 sub coercion_export_generator {
201 my $code = $class->next::method(@_);
203 my $value = $code->(@_);
204 warn "Coercion returned undef!"
205 unless defined $value;
212 This class wraps the coercion generator (e.g., C<to_Int()>) and warns
213 if a coercion returned an undefined value. You can wrap any library
218 use MyWrapper MyLibrary => [qw( Foo Bar )],
219 Moose => [qw( Str Int )];
224 The C<Moose> library name is a special shortcut for
225 L<MooseX::Types::Moose>.
227 =head2 Generator methods you can overload
231 =item type_export_generator( $short, $full )
233 Creates a closure returning the type's L<Moose::Meta::TypeConstraint>
236 =item check_export_generator( $short, $full, $undef_message )
238 This creates the closure used to test if a value is valid for this type.
240 =item coercion_export_generator( $short, $full, $undef_message )
242 This is the closure that's doing coercions.
246 =head2 Provided Parameters
252 The short, exported name of the type.
256 The fully qualified name of this type as L<Moose> knows it.
260 A message that will be thrown when type functionality is used but the
261 type does not yet exist.
263 =head1 RECURSIVE SUBTYPES
265 As of version 0.08, L<Moose::Types> has experimental support for Recursive
266 subtypes. This will allow:
268 subtype Tree() => as HashRef[Str|Tree];
270 Which validates things like:
273 {key=>{subkey1=>'value', subkey2=>'value'}}
275 And so on. This feature is new and there may be lurking bugs so don't be afraid
276 to hunt me down with patches and test cases if you have trouble.
278 =head1 NOTES REGARDING TYPE UNIONS
280 L<MooseX::Types> uses L<MooseX::Types::TypeDecorator> to do some overloading
281 which generally allows you to easily create union types:
283 subtype StrOrArrayRef,
286 As with parameterized constrains, this overloading extends to modules using the
287 types you define in a type library.
290 use MooseX::Types::Moose qw(HashRef Int);
292 has 'attr' => (isa=>HashRef|Int);
294 And everything should just work as you'd think.
300 Installs the L<MooseX::Types::Base> class into the caller and
301 exports types according to the specification described in
302 L</"LIBRARY DEFINITION">. This will continue to
303 L<Moose::Util::TypeConstraints>' C<import> method to export helper
304 functions you will need to declare your types.
309 my ($class, %args) = @_;
312 # everyone should want this
316 # inject base class into new library
318 unshift @{ $callee . '::ISA' }, 'MooseX::Types::Base';
321 # generate predeclared type helpers
322 if (my @orig_declare = @{ $args{ -declare } || [] }) {
323 my ($tags, $declare) = filter_tags @orig_declare;
326 for my $type (@$declare) {
328 croak "Cannot create a type containing '::' ($type) at the moment"
331 # add type to library and remember to export
332 $callee->add_type($type);
333 push @to_export, $type;
336 $callee->import({ -full => 1, -into => $callee }, @to_export);
339 # run type constraints import
340 return Moose::Util::TypeConstraints->import({ into => $callee });
343 =head2 type_export_generator
345 Generate a type export, e.g. C<Int()>. This will return either a
346 L<Moose::Meta::TypeConstraint> object, or alternatively a
347 L<MooseX::Types::UndefinedType> object if the type was not
352 sub type_export_generator {
353 my ($class, $type, $name) = @_;
355 ## Return an anonymous subroutine that will generate the proxied type
356 ## constraint for you.
360 if(defined(my $params = shift @_)) {
361 ## We currently only allow a TC to accept a single, ArrayRef
362 ## parameter, as in HashRef[Int], where [Int] is what's inside the
364 if(ref $params eq 'ARRAY') {
365 $type_constraint = $class->create_arged_type_constraint($name, @$params);
367 croak 'Arguments must be an ArrayRef, not '. ref $params;
370 $type_constraint = $class->create_base_type_constraint($name);
373 $type_constraint = defined($type_constraint) ? $type_constraint
374 : MooseX::Types::UndefinedType->new($name);
376 my $type_decorator = $class->create_type_decorator($type_constraint);
378 ## If there are additional args, that means it's probably stuff that
379 ## needs to be returned to the subtype. Not an ideal solution here but
380 ## doesn't seem to cause trouble.
383 return ($type_decorator, @_);
385 return $type_decorator;
390 =head2 create_arged_type_constraint ($name, @args)
392 Given a String $name with @args find the matching typeconstraint and parameterize
397 sub create_arged_type_constraint {
398 my ($class, $name, @args) = @_;
399 my $type_constraint = Moose::Util::TypeConstraints::find_or_create_type_constraint("$name");
400 return $type_constraint->parameterize(@args);
403 =head2 create_base_type_constraint ($name)
405 Given a String $name, find the matching typeconstraint.
409 sub create_base_type_constraint {
410 my ($class, $name) = @_;
411 return find_type_constraint($name);
414 =head2 create_type_decorator ($type_constraint)
416 Given a $type_constraint, return a lightweight L<MooseX::Types::TypeDecorator>
421 sub create_type_decorator {
422 my ($class, $type_constraint) = @_;
423 return MooseX::Types::TypeDecorator->new($type_constraint);
426 =head2 coercion_export_generator
428 This generates a coercion handler function, e.g. C<to_Int($value)>.
432 sub coercion_export_generator {
433 my ($class, $type, $full, $undef_msg) = @_;
437 # we need a type object
438 my $tobj = find_type_constraint($full) or croak $undef_msg;
439 my $return = $tobj->coerce($value);
441 # non-successful coercion returns false
442 return unless $tobj->check($return);
448 =head2 check_export_generator
450 Generates a constraint check closure, e.g. C<is_Int($value)>.
454 sub check_export_generator {
455 my ($class, $type, $full, $undef_msg) = @_;
459 # we need a type object
460 my $tobj = find_type_constraint($full) or croak $undef_msg;
462 return $tobj->check($value);
468 The following are lists of gotcha's and their workarounds for developers coming
469 from the standard string based type constraint names
473 A library makes the types quasi-unique by prefixing their names with (by
474 default) the library package name. If you're only using the type handler
475 functions provided by MooseX::Types, you shouldn't ever have to use
476 a type's actual full name.
478 =head2 Argument separation ('=>' versus ',')
480 The Perlop manpage has this to say about the '=>' operator: "The => operator is
481 a synonym for the comma, but forces any word (consisting entirely of word
482 characters) to its left to be interpreted as a string (as of 5.001). This
483 includes words that might otherwise be considered a constant or function call."
485 Due to this stringification, the following will NOT work as you might think:
487 subtype StrOrArrayRef => as Str|ArrayRef;
489 The 'StrOrArrayRef' will have it's stringification activated this causes the
490 subtype to not be created. Since the bareword type constraints are not strings
491 you really should not try to treat them that way. You will have to use the ','
492 operator instead. The author's of this package realize that all the L<Moose>
493 documention and examples nearly uniformly use the '=>' version of the comma
494 operator and this could be an issue if you are converting code.
496 Patches welcome for discussion.
498 =head2 Compatibility with Sub::Exporter
500 If you want to use L<Sub::Exporter> with a Type Library, you need to make sure
501 you export all the type constraints declared AS WELL AS any additional export
502 targets. For example if you do:
504 package TypeAndSubExporter; {
506 use MooseX::Types::Moose qw(Str);
507 use MooseX::Types -declare => [qw(MyStr)];
508 use Sub::Exporter -setup => { exports => [ qw(something) ] };
520 use TypeAndSubExporter qw(MyStr);
523 You'll get a '"MyStr" is not exported by the TypeAndSubExporter module' error.
524 Upi can workaround by:
526 - use Sub::Exporter -setup => { exports => [ qw(something) ] };
527 + use Sub::Exporter -setup => { exports => [ qw(something MyStr) ] };
529 This is a workaround and I am exploring how to make these modules work better
530 together. I realize this workaround will lead a lot of duplication in your
531 export declarations and will be onerous for large type libraries. Patches and
532 detailed test cases welcome. See the tests directory for a start on this.
537 L<Moose::Util::TypeConstraints>,
538 L<MooseX::Types::Moose>,
541 =head1 AUTHOR AND COPYRIGHT
543 Robert 'phaylon' Sedlacek C<E<lt>rs@474.atE<gt>>, with many thanks to
544 the C<#moose> cabal on C<irc.perl.org>.
546 Additional features by John Napiorkowski (jnapiorkowski) <jjnapiork@cpan.org>.
550 This program is free software; you can redistribute it and/or modify
551 it under the same terms as perl itself.