5 MooseX::Types - Organise your Moose types in libraries
13 use Moose::Util::TypeConstraints;
14 use MooseX::Types::Base ();
15 use MooseX::Types::Util qw( filter_tags );
16 use MooseX::Types::UndefinedType;
17 use Sub::Install qw( install_sub );
21 use namespace::clean -except => [qw( meta )];
25 my $UndefMsg = q{Action for type '%s' not yet defined in library '%s'};
29 =head2 Library Definition
34 # predeclare our own types
36 -declare => [qw( PositiveInt NegativeInt )];
38 # import builtin types
39 use MooseX::Types::Moose 'Int';
45 message { "Int is not larger than 0" };
50 message { "Int is not smaller than 0" };
63 use MyLibrary qw( PositiveInt NegativeInt );
65 # use the exported constants as type names
77 print "positive\n" if is_PositiveInt($value);
78 print "negative\n" if is_NegativeInt($value);
80 # coerce the value, NegativeInt doesn't have a coercion
81 # helper, since it didn't define any coercions.
82 $value = to_PositiveInt($value) or die "Cannot coerce";
89 The types provided with L<Moose> are by design global. This package helps
90 you to organise and selectively import your own and the built-in types in
91 libraries. As a nice side effect, it catches typos at compile-time too.
93 However, the main reason for this module is to provide an easy way to not
94 have conflicts with your type names, since the internal fully qualified
95 names of the types will be prefixed with the library's name.
97 This module will also provide you with some helper functions to make it
98 easier to use Moose types in your code.
100 =head1 TYPE HANDLER FUNCTIONS
104 A constant with the name of your type. It contains the type's fully
105 qualified name. Takes no value, as all constants.
109 This handler takes a value and tests if it is a valid value for this
110 C<$type>. It will return true or false.
114 A handler that will take a value and coerce it into the C<$type>. It will
115 return a false value if the type could not be coerced.
117 B<Important Note>: This handler will only be exported for types that can
118 do type coercion. This has the advantage that a coercion to a type that
119 cannot hasn't defined any coercions will lead to a compile-time error.
121 =head1 LIBRARY DEFINITION
123 A MooseX::Types is just a normal Perl module. Unlike Moose
124 itself, it does not install C<use strict> and C<use warnings> in your
125 class by default, so this is up to you.
127 The only thing a library is required to do is
129 use MooseX::Types -declare => \@types;
131 with C<@types> being a list of types you wish to define in this library.
132 This line will install a proper base class in your package as well as the
133 full set of L<handlers|/"TYPE HANDLER FUNCTIONS"> for your declared
134 types. It will then hand control over to L<Moose::Util::TypeConstraints>'
135 C<import> method to export the functions you will need to declare your
138 If you want to use Moose' built-in types (e.g. for subtyping) you will
141 use MooseX::Types::Moose @types;
143 to import the helpers from the shipped L<MooseX::Types::Moose>
144 library which can export all types that come with Moose.
146 You will have to define coercions for your types or your library won't
147 export a L</to_$type> coercion helper for it.
149 Note that you currently cannot define types containing C<::>, since
150 exporting would be a problem.
154 You can import the L<"type helpers"|/"TYPE HANDLER FUNCTIONS"> of a
155 library by C<use>ing it with a list of types to import as arguments. If
156 you want all of them, use the C<:all> tag. For example:
158 use MyLibrary ':all';
159 use MyOtherLibrary qw( TypeA TypeB );
161 MooseX::Types comes with a library of Moose' built-in types called
162 L<MooseX::Types::Moose>.
164 =head1 WRAPPING A LIBRARY
166 You can define your own wrapper subclasses to manipulate the behaviour
167 of a set of library exports. Here is an example:
172 use base 'MooseX::Types::Wrapper';
174 sub coercion_export_generator {
176 my $code = $class->next::method(@_);
178 my $value = $code->(@_);
179 warn "Coercion returned undef!"
180 unless defined $value;
187 This class wraps the coercion generator (e.g., C<to_Int()>) and warns
188 if a coercion returned an undefined value. You can wrap any library
193 use MyWrapper MyLibrary => [qw( Foo Bar )],
194 Moose => [qw( Str Int )];
199 The C<Moose> library name is a special shortcut for
200 L<MooseX::Types::Moose>.
202 =head2 Generator methods you can overload
206 =item type_export_generator( $short, $full )
208 Creates a closure returning the type's L<Moose::Meta::TypeConstraint>
211 =item check_export_generator( $short, $full, $undef_message )
213 This creates the closure used to test if a value is valid for this type.
215 =item coercion_export_generator( $short, $full, $undef_message )
217 This is the closure that's doing coercions.
221 =head2 Provided Parameters
227 The short, exported name of the type.
231 The fully qualified name of this type as L<Moose> knows it.
235 A message that will be thrown when type functionality is used but the
236 type does not yet exist.
244 Installs the L<MooseX::Types::Base> class into the caller and
245 exports types according to the specification described in
246 L</"LIBRARY DEFINITION">. This will continue to
247 L<Moose::Util::TypeConstraints>' C<import> method to export helper
248 functions you will need to declare your types.
253 my ($class, %args) = @_;
256 # inject base class into new library
258 unshift @{ $callee . '::ISA' }, 'MooseX::Types::Base';
261 # generate predeclared type helpers
262 if (my @orig_declare = @{ $args{ -declare } || [] }) {
263 my ($tags, $declare) = filter_tags @orig_declare;
265 for my $type (@$declare) {
267 croak "Cannot create a type containing '::' ($type) at the moment"
270 $callee->add_type($type);
271 $callee->export_type_into(
273 sprintf($UndefMsg, $type, $callee),
279 # run type constraints import
280 return Moose::Util::TypeConstraints->import({ into => $callee });
283 =head2 type_export_generator
285 Generate a type export, e.g. C<Int()>. This will return either a
286 L<Moose::Meta::TypeConstraint> object, or alternatively a
287 L<MooseX::Types::UndefinedType> object if the type was not
292 sub type_export_generator {
293 my ($class, $type, $full) = @_;
295 return find_type_constraint($full)
296 || MooseX::Types::UndefinedType->new($full);
300 =head2 coercion_export_generator
302 This generates a coercion handler function, e.g. C<to_Int($value)>.
306 sub coercion_export_generator {
307 my ($class, $type, $full, $undef_msg) = @_;
311 # we need a type object
312 my $tobj = find_type_constraint($full) or croak $undef_msg;
313 my $return = $tobj->coerce($value);
315 # non-successful coercion returns false
316 return unless $tobj->check($return);
322 =head2 check_export_generator
324 Generates a constraint check closure, e.g. C<is_Int($value)>.
328 sub check_export_generator {
329 my ($class, $type, $full, $undef_msg) = @_;
333 # we need a type object
334 my $tobj = find_type_constraint($full) or croak $undef_msg;
336 return $tobj->check($value);
342 A library makes the types quasi-unique by prefixing their names with (by
343 default) the library package name. If you're only using the type handler
344 functions provided by MooseX::Types, you shouldn't ever have to use
345 a type's actual full name.
349 L<Moose>, L<Moose::Util::TypeConstraints>, L<MooseX::Types::Moose>
351 =head1 AUTHOR AND COPYRIGHT
353 Robert 'phaylon' Sedlacek C<E<lt>rs@474.atE<gt>>, with many thanks to
354 the C<#moose> cabal on C<irc.perl.org>.
358 This program is free software; you can redistribute it and/or modify
359 it under the same terms as perl itself.