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
33 # predeclare our own types
35 -declare => [qw( PositiveInt NegativeInt )];
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" };
62 use MyLibrary qw( PositiveInt NegativeInt );
64 # use the exported constants as type names
76 print "positive\n" if is_PositiveInt($value);
77 print "negative\n" if is_NegativeInt($value);
79 # coerce the value, NegativeInt doesn't have a coercion
80 # helper, since it didn't define any coercions.
81 $value = to_PositiveInt($value) or die "Cannot coerce";
88 The types provided with L<Moose> are by design global. This package helps
89 you to organise and selectively import your own and the built-in types in
90 libraries. As a nice side effect, it catches typos at compile-time too.
92 However, the main reason for this module is to provide an easy way to not
93 have conflicts with your type names, since the internal fully qualified
94 names of the types will be prefixed with the library's name.
96 This module will also provide you with some helper functions to make it
97 easier to use Moose types in your code.
99 =head1 TYPE HANDLER FUNCTIONS
103 A constant with the name of your type. It contains the type's fully
104 qualified name. Takes no value, as all constants.
108 This handler takes a value and tests if it is a valid value for this
109 C<$type>. It will return true or false.
113 A handler that will take a value and coerce it into the C<$type>. It will
114 return a false value if the type could not be coerced.
116 B<Important Note>: This handler will only be exported for types that can
117 do type coercion. This has the advantage that a coercion to a type that
118 cannot hasn't defined any coercions will lead to a compile-time error.
120 =head1 LIBRARY DEFINITION
122 A MooseX::Types is just a normal Perl module. Unlike Moose
123 itself, it does not install C<use strict> and C<use warnings> in your
124 class by default, so this is up to you.
126 The only thing a library is required to do is
128 use MooseX::Types -declare => \@types;
130 with C<@types> being a list of types you wish to define in this library.
131 This line will install a proper base class in your package as well as the
132 full set of L<handlers|/"TYPE HANDLER FUNCTIONS"> for your declared
133 types. It will then hand control over to L<Moose::Util::TypeConstraints>'
134 C<import> method to export the functions you will need to declare your
137 If you want to use Moose' built-in types (e.g. for subtyping) you will
140 use MooseX::Types::Moose @types;
142 to import the helpers from the shipped L<MooseX::Types::Moose>
143 library which can export all types that come with Moose.
145 You will have to define coercions for your types or your library won't
146 export a L</to_$type> coercion helper for it.
148 Note that you currently cannot define types containing C<::>, since
149 exporting would be a problem.
151 You also don't need to use C<warnings> and C<strict>, since the
152 definition of a library automatically exports those.
156 You can import the L<"type helpers"|/"TYPE HANDLER FUNCTIONS"> of a
157 library by C<use>ing it with a list of types to import as arguments. If
158 you want all of them, use the C<:all> tag. For example:
160 use MyLibrary ':all';
161 use MyOtherLibrary qw( TypeA TypeB );
163 MooseX::Types comes with a library of Moose' built-in types called
164 L<MooseX::Types::Moose>.
166 =head1 WRAPPING A LIBRARY
168 You can define your own wrapper subclasses to manipulate the behaviour
169 of a set of library exports. Here is an example:
174 use base 'MooseX::Types::Wrapper';
176 sub coercion_export_generator {
178 my $code = $class->next::method(@_);
180 my $value = $code->(@_);
181 warn "Coercion returned undef!"
182 unless defined $value;
189 This class wraps the coercion generator (e.g., C<to_Int()>) and warns
190 if a coercion returned an undefined value. You can wrap any library
195 use MyWrapper MyLibrary => [qw( Foo Bar )],
196 Moose => [qw( Str Int )];
201 The C<Moose> library name is a special shortcut for
202 L<MooseX::Types::Moose>.
204 =head2 Generator methods you can overload
208 =item type_export_generator( $short, $full )
210 Creates a closure returning the type's L<Moose::Meta::TypeConstraint>
213 =item check_export_generator( $short, $full, $undef_message )
215 This creates the closure used to test if a value is valid for this type.
217 =item coercion_export_generator( $short, $full, $undef_message )
219 This is the closure that's doing coercions.
223 =head2 Provided Parameters
229 The short, exported name of the type.
233 The fully qualified name of this type as L<Moose> knows it.
237 A message that will be thrown when type functionality is used but the
238 type does not yet exist.
246 Installs the L<MooseX::Types::Base> class into the caller and
247 exports types according to the specification described in
248 L</"LIBRARY DEFINITION">. This will continue to
249 L<Moose::Util::TypeConstraints>' C<import> method to export helper
250 functions you will need to declare your types.
255 my ($class, %args) = @_;
258 # everyone should want this
262 # inject base class into new library
264 unshift @{ $callee . '::ISA' }, 'MooseX::Types::Base';
267 # generate predeclared type helpers
268 if (my @orig_declare = @{ $args{ -declare } || [] }) {
269 my ($tags, $declare) = filter_tags @orig_declare;
271 for my $type (@$declare) {
273 croak "Cannot create a type containing '::' ($type) at the moment"
276 $callee->add_type($type);
277 $callee->export_type_into(
279 sprintf($UndefMsg, $type, $callee),
285 # run type constraints import
286 return Moose::Util::TypeConstraints->import({ into => $callee });
289 =head2 type_export_generator
291 Generate a type export, e.g. C<Int()>. This will return either a
292 L<Moose::Meta::TypeConstraint> object, or alternatively a
293 L<MooseX::Types::UndefinedType> object if the type was not
298 sub type_export_generator {
299 my ($class, $type, $full) = @_;
301 return find_type_constraint($full)
302 || MooseX::Types::UndefinedType->new($full);
306 =head2 coercion_export_generator
308 This generates a coercion handler function, e.g. C<to_Int($value)>.
312 sub coercion_export_generator {
313 my ($class, $type, $full, $undef_msg) = @_;
317 # we need a type object
318 my $tobj = find_type_constraint($full) or croak $undef_msg;
319 my $return = $tobj->coerce($value);
321 # non-successful coercion returns false
322 return unless $tobj->check($return);
328 =head2 check_export_generator
330 Generates a constraint check closure, e.g. C<is_Int($value)>.
334 sub check_export_generator {
335 my ($class, $type, $full, $undef_msg) = @_;
339 # we need a type object
340 my $tobj = find_type_constraint($full) or croak $undef_msg;
342 return $tobj->check($value);
348 A library makes the types quasi-unique by prefixing their names with (by
349 default) the library package name. If you're only using the type handler
350 functions provided by MooseX::Types, you shouldn't ever have to use
351 a type's actual full name.
355 L<Moose>, L<Moose::Util::TypeConstraints>, L<MooseX::Types::Moose>
357 =head1 AUTHOR AND COPYRIGHT
359 Robert 'phaylon' Sedlacek C<E<lt>rs@474.atE<gt>>, with many thanks to
360 the C<#moose> cabal on C<irc.perl.org>.
364 This program is free software; you can redistribute it and/or modify
365 it under the same terms as perl itself.