6 MooseX::Types - Organise your Moose types in libraries
13 use Moose::Util::TypeConstraints;
14 use MooseX::Types::TypeDecorator;
15 use MooseX::Types::Base ();
16 use MooseX::Types::Util qw( filter_tags );
17 use MooseX::Types::UndefinedType;
18 use Carp::Clan qw( ^MooseX::Types );
20 use namespace::clean -except => [qw( meta )];
24 my $UndefMsg = q{Action for type '%s' not yet defined in library '%s'};
28 =head2 Library Definition
32 # predeclare our own types
34 -declare => [qw( PositiveInt NegativeInt )];
36 # import builtin types
37 use MooseX::Types::Moose 'Int';
43 message { "Int is not larger than 0" };
48 message { "Int is not smaller than 0" };
61 use MyLibrary qw( PositiveInt NegativeInt );
63 # use the exported constants as type names
75 print "positive\n" if is_PositiveInt($value);
76 print "negative\n" if is_NegativeInt($value);
78 # coerce the value, NegativeInt doesn't have a coercion
79 # helper, since it didn't define any coercions.
80 $value = to_PositiveInt($value) or die "Cannot coerce";
87 The types provided with L<Moose> are by design global. This package helps
88 you to organise and selectively import your own and the built-in types in
89 libraries. As a nice side effect, it catches typos at compile-time too.
91 However, the main reason for this module is to provide an easy way to not
92 have conflicts with your type names, since the internal fully qualified
93 names of the types will be prefixed with the library's name.
95 This module will also provide you with some helper functions to make it
96 easier to use Moose types in your code.
98 =head1 TYPE HANDLER FUNCTIONS
102 A constant with the name of your type. It contains the type's fully
103 qualified name. Takes no value, as all constants.
107 This handler takes a value and tests if it is a valid value for this
108 C<$type>. It will return true or false.
112 A handler that will take a value and coerce it into the C<$type>. It will
113 return a false value if the type could not be coerced.
115 B<Important Note>: This handler will only be exported for types that can
116 do type coercion. This has the advantage that a coercion to a type that
117 cannot hasn't defined any coercions will lead to a compile-time error.
119 =head1 LIBRARY DEFINITION
121 A MooseX::Types is just a normal Perl module. Unlike Moose
122 itself, it does not install C<use strict> and C<use warnings> in your
123 class by default, so this is up to you.
125 The only thing a library is required to do is
127 use MooseX::Types -declare => \@types;
129 with C<@types> being a list of types you wish to define in this library.
130 This line will install a proper base class in your package as well as the
131 full set of L<handlers|/"TYPE HANDLER FUNCTIONS"> for your declared
132 types. It will then hand control over to L<Moose::Util::TypeConstraints>'
133 C<import> method to export the functions you will need to declare your
136 If you want to use Moose' built-in types (e.g. for subtyping) you will
139 use MooseX::Types::Moose @types;
141 to import the helpers from the shipped L<MooseX::Types::Moose>
142 library which can export all types that come with Moose.
144 You will have to define coercions for your types or your library won't
145 export a L</to_$type> coercion helper for it.
147 Note that you currently cannot define types containing C<::>, since
148 exporting would be a problem.
150 You also don't need to use C<warnings> and C<strict>, since the
151 definition of a library automatically exports those.
155 You can import the L<"type helpers"|/"TYPE HANDLER FUNCTIONS"> of a
156 library by C<use>ing it with a list of types to import as arguments. If
157 you want all of them, use the C<:all> tag. For example:
159 use MyLibrary ':all';
160 use MyOtherLibrary qw( TypeA TypeB );
162 MooseX::Types comes with a library of Moose' built-in types called
163 L<MooseX::Types::Moose>.
165 The exporting mechanism is, since version 0.5, implemented via a wrapper
166 around L<Sub::Exporter>. This means you can do something like this:
168 use MyLibrary TypeA => { -as => 'MyTypeA' },
169 TypeB => { -as => 'MyTypeB' };
171 =head1 WRAPPING A LIBRARY
173 You can define your own wrapper subclasses to manipulate the behaviour
174 of a set of library exports. Here is an example:
179 use base 'MooseX::Types::Wrapper';
181 sub coercion_export_generator {
183 my $code = $class->next::method(@_);
185 my $value = $code->(@_);
186 warn "Coercion returned undef!"
187 unless defined $value;
194 This class wraps the coercion generator (e.g., C<to_Int()>) and warns
195 if a coercion returned an undefined value. You can wrap any library
200 use MyWrapper MyLibrary => [qw( Foo Bar )],
201 Moose => [qw( Str Int )];
206 The C<Moose> library name is a special shortcut for
207 L<MooseX::Types::Moose>.
209 =head2 Generator methods you can overload
213 =item type_export_generator( $short, $full )
215 Creates a closure returning the type's L<Moose::Meta::TypeConstraint>
218 =item check_export_generator( $short, $full, $undef_message )
220 This creates the closure used to test if a value is valid for this type.
222 =item coercion_export_generator( $short, $full, $undef_message )
224 This is the closure that's doing coercions.
228 =head2 Provided Parameters
234 The short, exported name of the type.
238 The fully qualified name of this type as L<Moose> knows it.
242 A message that will be thrown when type functionality is used but the
243 type does not yet exist.
251 Installs the L<MooseX::Types::Base> class into the caller and
252 exports types according to the specification described in
253 L</"LIBRARY DEFINITION">. This will continue to
254 L<Moose::Util::TypeConstraints>' C<import> method to export helper
255 functions you will need to declare your types.
260 my ($class, %args) = @_;
263 # everyone should want this
267 # inject base class into new library
269 unshift @{ $callee . '::ISA' }, 'MooseX::Types::Base';
272 # generate predeclared type helpers
273 if (my @orig_declare = @{ $args{ -declare } || [] }) {
274 my ($tags, $declare) = filter_tags @orig_declare;
277 for my $type (@$declare) {
279 croak "Cannot create a type containing '::' ($type) at the moment"
282 # add type to library and remember to export
283 $callee->add_type($type);
284 push @to_export, $type;
287 $callee->import({ -full => 1, -into => $callee }, @to_export);
290 # run type constraints import
291 return Moose::Util::TypeConstraints->import({ into => $callee });
294 =head2 type_export_generator
296 Generate a type export, e.g. C<Int()>. This will return either a
297 L<Moose::Meta::TypeConstraint> object, or alternatively a
298 L<MooseX::Types::UndefinedType> object if the type was not
303 sub type_export_generator {
304 my ($class, $type, $name) = @_;
307 if(my $params = shift @_) {
308 $type_constraint = $class->create_arged_type_constraint($name, @$params);
310 $type_constraint = $class->create_base_type_constraint($name)
311 || MooseX::Types::UndefinedType->new($name);
313 return $class->create_type_decorator($type_constraint);
317 =head2 create_arged_type_constraint ($name, @args)
319 Given a String $name with @args find the matching typeconstraint.
323 sub create_arged_type_constraint {
324 my ($class, $name, @args) = @_;
325 ### This whole section is a real TODO :) Ugly hack to get the base tests working.
326 my $fullname = $name."[$args[0]]";
327 return Moose::Util::TypeConstraints::create_parameterized_type_constraint($fullname);
330 =head2 create_base_type_constraint ($name)
332 Given a String $name, find the matching typeconstraint.
336 sub create_base_type_constraint {
337 my ($class, $name) = @_;
338 return find_type_constraint($name);
341 =head2 create_type_decorator ($type_constraint)
343 Given a $type_constraint, return a lightweight L<MooseX::Types::TypeDecorator>
348 sub create_type_decorator {
349 my ($class, $type_constraint) = @_;
350 return MooseX::Types::TypeDecorator->new(type_constraint=>$type_constraint);
353 =head2 coercion_export_generator
355 This generates a coercion handler function, e.g. C<to_Int($value)>.
359 sub coercion_export_generator {
360 my ($class, $type, $full, $undef_msg) = @_;
364 # we need a type object
365 my $tobj = find_type_constraint($full) or croak $undef_msg;
366 my $return = $tobj->coerce($value);
368 # non-successful coercion returns false
369 return unless $tobj->check($return);
375 =head2 check_export_generator
377 Generates a constraint check closure, e.g. C<is_Int($value)>.
381 sub check_export_generator {
382 my ($class, $type, $full, $undef_msg) = @_;
386 # we need a type object
387 my $tobj = find_type_constraint($full) or croak $undef_msg;
389 return $tobj->check($value);
395 A library makes the types quasi-unique by prefixing their names with (by
396 default) the library package name. If you're only using the type handler
397 functions provided by MooseX::Types, you shouldn't ever have to use
398 a type's actual full name.
403 L<Moose::Util::TypeConstraints>,
404 L<MooseX::Types::Moose>,
407 =head1 AUTHOR AND COPYRIGHT
409 Robert 'phaylon' Sedlacek C<E<lt>rs@474.atE<gt>>, with many thanks to
410 the C<#moose> cabal on C<irc.perl.org>.
414 This program is free software; you can redistribute it and/or modify
415 it under the same terms as perl itself.