4 # ABSTRACT: Organise your Moose types in libraries
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 );
14 use Scalar::Util 'reftype';
16 use namespace::autoclean;
19 my $UndefMsg = q{Action for type '%s' not yet defined in library '%s'};
25 =head2 Library Definition
29 # predeclare our own types
30 use MooseX::Types -declare => [
35 ArrayRefOfAtLeastThreeNegativeInts
36 LotsOfInnerConstraints
42 # import builtin types
43 use MooseX::Types::Moose qw/Int HashRef/;
49 message { "Int is not larger than 0" };
54 message { "Int is not smaller than 0" };
61 # with parameterized constraints.
63 subtype ArrayRefOfPositiveInt,
64 as ArrayRef[PositiveInt];
66 subtype ArrayRefOfAtLeastThreeNegativeInts,
67 as ArrayRef[NegativeInt],
68 where { scalar(@$_) > 2 };
70 subtype LotsOfInnerConstraints,
71 as ArrayRef[ArrayRef[HashRef[Int]]];
73 # with TypeConstraint Unions
75 subtype StrOrArrayRef,
80 class_type 'DateTime';
84 class_type MyDateTime, { class => 'DateTime' };
88 via { DateTime->new(%$_) };
96 use MyLibrary qw( PositiveInt NegativeInt );
98 # use the exported constants as type names
110 print "positive\n" if is_PositiveInt($value);
111 print "negative\n" if is_NegativeInt($value);
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";
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.
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
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.
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.
139 This module also provides some helper functions for using Moose types outside
140 of attribute declarations.
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">.
147 =head1 LIBRARY DEFINITION
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.
153 The only thing a library is required to do is
155 use MooseX::Types -declare => \@types;
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
164 If you want to use Moose' built-in types (e.g. for subtyping) you will
167 use MooseX::Types::Moose @types;
169 to import the helpers from the shipped L<MooseX::Types::Moose>
170 library which can export all types that come with Moose.
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.
175 Note that you currently cannot define types containing C<::>, since
176 exporting would be a problem.
178 You also don't need to use C<warnings> and C<strict>, since the
179 definition of a library automatically exports those.
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:
187 use MyLibrary ':all';
188 use MyOtherLibrary qw( TypeA TypeB );
190 MooseX::Types comes with a library of Moose' built-in types called
191 L<MooseX::Types::Moose>.
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:
196 use MyLibrary TypeA => { -as => 'MyTypeA' },
197 TypeB => { -as => 'MyTypeB' };
199 =head1 TYPE HANDLER FUNCTIONS
203 A constant with the name of your type. It contains the type's fully
204 qualified name. Takes no value, as all constants.
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.
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.
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.
220 =head1 WRAPPING A LIBRARY
222 You can define your own wrapper subclasses to manipulate the behaviour
223 of a set of library exports. Here is an example:
228 use base 'MooseX::Types::Wrapper';
230 sub coercion_export_generator {
232 my $code = $class->next::method(@_);
234 my $value = $code->(@_);
235 warn "Coercion returned undef!"
236 unless defined $value;
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
249 use MyWrapper MyLibrary => [qw( Foo Bar )],
250 Moose => [qw( Str Int )];
255 The C<Moose> library name is a special shortcut for L<MooseX::Types::Moose>.
257 =head2 Generator methods you can overload
261 =item type_export_generator( $short, $full )
263 Creates a closure returning the type's L<Moose::Meta::TypeConstraint> object.
265 =item check_export_generator( $short, $full, $undef_message )
267 This creates the closure used to test if a value is valid for this type.
269 =item coercion_export_generator( $short, $full, $undef_message )
271 This is the closure that's doing coercions.
275 =head2 Provided Parameters
281 The short, exported name of the type.
285 The fully qualified name of this type as L<Moose> knows it.
289 A message that will be thrown when type functionality is used but the
290 type does not yet exist.
294 =head1 RECURSIVE SUBTYPES
296 As of version 0.08, L<Moose::Types> has experimental support for Recursive
297 subtypes. This will allow:
299 subtype Tree() => as HashRef[Str|Tree];
301 Which validates things like:
304 {key=>{subkey1=>'value', subkey2=>'value'}}
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.
309 =head1 NOTES REGARDING TYPE UNIONS
311 L<MooseX::Types> uses L<MooseX::Types::TypeDecorator> to do some overloading
312 which generally allows you to easily create union types:
314 subtype StrOrArrayRef,
317 As with parameterized constraints, this overloading extends to modules using the
318 types you define in a type library.
321 use MooseX::Types::Moose qw(HashRef Int);
323 has 'attr' => ( isa => HashRef | Int );
325 And everything should just work as you'd think.
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.
339 my ($class, %args) = @_;
342 # everyone should want this
346 # inject base class into new library
348 unshift @{ $caller . '::ISA' }, 'MooseX::Types::Base';
351 # generate predeclared type helpers
352 if (my @orig_declare = @{ $args{ -declare } || [] }) {
353 my ($tags, $declare) = filter_tags @orig_declare;
356 for my $type (@$declare) {
358 croak "Cannot create a type containing '::' ($type) at the moment"
361 # add type to library and remember to export
362 $caller->add_type($type);
363 push @to_export, $type;
366 $caller->import({ -full => 1, -into => $caller }, @to_export);
369 # run type constraints import
370 Moose::Util::TypeConstraints->import({ into => $caller });
372 # override some with versions that check for syntax errors
373 MooseX::Types::CheckedUtilExports->import({ into => $caller });
378 =head2 type_export_generator
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.
386 sub type_export_generator {
387 my ($class, $type, $name) = @_;
389 ## Return an anonymous subroutine that will generate the proxied type
390 ## constraint for you.
392 return subname "__TYPE__::$name" => sub {
393 my $type_constraint = $class->create_base_type_constraint($name);
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
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"
405 croak "Argument must be an ArrayRef to create a parameterized "
406 . "type, Eg.: ${type}[Int]. Got: ".ref($params)."."
410 $type_constraint = defined($type_constraint) ? $type_constraint
411 : MooseX::Types::UndefinedType->new($name);
413 my $type_decorator = $class->create_type_decorator($type_constraint);
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.
420 return ($type_decorator, @_);
422 return $type_decorator;
427 =head2 create_arged_type_constraint ($name, @args)
429 Given a String $name with @args find the matching type constraint and parameterize
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.
444 # Moose::Util::TypeConstraints::find_type_constraint($parameterized->name)) {
447 # Moose::Util::TypeConstraints::register_type_constraint($parameterized);
448 return $parameterized;
451 =head2 create_base_type_constraint ($name)
453 Given a String $name, find the matching type constraint.
457 sub create_base_type_constraint {
458 my ($class, $name) = @_;
459 return find_type_constraint($name);
462 =head2 create_type_decorator ($type_constraint)
464 Given a $type_constraint, return a lightweight L<MooseX::Types::TypeDecorator>
469 sub create_type_decorator {
470 my ($class, $type_constraint) = @_;
471 return MooseX::Types::TypeDecorator->new($type_constraint);
474 =head2 coercion_export_generator
476 This generates a coercion handler function, e.g. C<to_Int($value)>.
480 sub coercion_export_generator {
481 my ($class, $type, $full, $undef_msg) = @_;
485 # we need a type object
486 my $tobj = find_type_constraint($full) or croak $undef_msg;
487 my $return = $tobj->coerce($value);
489 # non-successful coercion returns false
490 return unless $tobj->check($return);
496 =head2 check_export_generator
498 Generates a constraint check closure, e.g. C<is_Int($value)>.
502 sub check_export_generator {
503 my ($class, $type, $full, $undef_msg) = @_;
507 # we need a type object
508 my $tobj = find_type_constraint($full) or croak $undef_msg;
510 return $tobj->check($value);
516 The following are lists of gotchas and their workarounds for developers coming
517 from the standard string based type constraint names
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.
526 =head2 Argument separation ('=>' versus ',')
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."
533 Due to this stringification, the following will NOT work as you might think:
535 subtype StrOrArrayRef => as Str | ArrayRef;
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.
544 Patches welcome for discussion.
546 =head2 Compatibility with Sub::Exporter
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:
552 package TypeAndSubExporter;
554 use MooseX::Types::Moose qw(Str);
555 use MooseX::Types -declare => [qw(MyStr)];
556 use Sub::Exporter -setup => { exports => [qw(something)] };
558 subtype MyStr, as Str;
564 # then in another module ...
567 use TypeAndSubExporter qw(MyStr);
569 You'll get a C<< "MyStr" is not exported by the TypeAndSubExporter module >> error.
570 It can be worked around by:
572 - use Sub::Exporter -setup => { exports => [ qw(something) ] };
573 + use Sub::Exporter -setup => { exports => [ qw(something MyStr) ] };
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.
580 =head1 COMBINING TYPE LIBRARIES
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>.
585 The L<MooseX::Types::Combine> module provides a simple API for combining a set
586 of type libraries together.
590 L<Moose>, L<Moose::Util::TypeConstraints>, L<MooseX::Types::Moose>,
593 =head1 ACKNOWLEDGEMENTS
595 Many thanks to the C<#moose> cabal on C<irc.perl.org>.