lib/MooseX/Types.pm

   1 package MooseX::Types;
   2
   3 =head1 NAME
   4
   5 MooseX::Types - Organise your Moose types in libraries
   6
   7 =cut
   8
   9 #use warnings;
  10 #use strict;
  11
  12 use Sub::Uplevel;
  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 );
  18 use Moose;
  19 use namespace::clean;
  20
  21 our $VERSION = 0.01;
  22
  23 my $UndefMsg = q{Action for type '%s' not yet defined in library '%s'};
  24
  25 =head1 SYNOPSIS
  26
  27   #
  28   # Library Definition
  29   #
  30   package MyLibrary;
  31   use strict;
  32
  33   # predeclare our own types
  34   use MooseX::Types
  35       -declare => [qw( PositiveInt NegativeInt )];
  36
  37   # import builtin types
  38   use MooseX::Types::Moose 'Int';
  39
  40   # type definition
  41   subtype PositiveInt,
  42       as Int,
  43       where { $_ > 0 },
  44       message { "Int is not larger than 0" };
  45
  46   subtype NegativeInt,
  47       as Int,
  48       where { $_ < 0 },
  49       message { "Int is not smaller than 0" };
  50
  51   # type coercion
  52   coerce PositiveInt,
  53       from Int,
  54           via { 1 };
  55
  56   1;
  57
  58   #
  59   # Usage
  60   #
  61   package Foo;
  62   use Moose;
  63   use MyLibrary qw( PositiveInt NegativeInt );
  64
  65   # use the exported constants as type names
  66   has 'bar',
  67       isa    => PositiveInt,
  68       is     => 'rw';
  69   has 'baz',
  70       isa    => NegativeInt,
  71       is     => 'rw';
  72
  73   sub quux {
  74       my ($self, $value);
  75
  76       # test the value
  77       print "positive\n" if is_PositiveInt($value);
  78       print "negative\n" if is_NegativeInt($value);
  79
  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";
  83   }
  84
  85   1;
  86
  87 =head1 DESCRIPTION
  88
  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.
  92
  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.
  96
  97 This module will also provide you with some helper functions to make it
  98 easier to use Moose types in your code.
  99
 100 =head1 TYPE HANDLER FUNCTIONS
 101
 102 =head2 $type
 103
 104 A constant with the name of your type. It contains the type's fully
 105 qualified name. Takes no value, as all constants.
 106
 107 =head2 is_$type
 108
 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.
 111
 112 =head2 to_$type
 113
 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.
 116
 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.
 120
 121 =head1 LIBRARY DEFINITION
 122
 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.
 126
 127 The only thing a library is required to do is
 128
 129   use MooseX::Types -declare => \@types;
 130
 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
 136 types.
 137
 138 If you want to use Moose' built-in types (e.g. for subtyping) you will
 139 want to
 140
 141   use MooseX::Types::Moose @types;
 142
 143 to import the helpers from the shipped L<MooseX::Types::Moose>
 144 library which can export all types that come with Moose.
 145
 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.
 148
 149 =head1 LIBRARY USAGE
 150
 151 You can import the L<"type helpers"|/"TYPE HANDLER FUNCTIONS"> of a
 152 library by C<use>ing it with a list of types to import as arguments. If
 153 you want all of them, use the C<:all> tag. For example:
 154
 155   use MyLibrary      ':all';
 156   use MyOtherLibrary qw( TypeA TypeB );
 157
 158 MooseX::Types comes with a library of Moose' built-in types called
 159 L<MooseX::Types::Moose>.
 160
 161 =head1 WRAPPING A LIBRARY
 162
 163 You can define your own wrapper subclasses to manipulate the behaviour
 164 of a set of library exports. Here is an example:
 165
 166   package MyWrapper;
 167   use strict;
 168   use Class::C3;
 169   use base 'MooseX::Types::Wrapper';
 170
 171   sub coercion_export_generator {
 172       my $class = shift;
 173       my $code = $class->next::method(@_);
 174       return sub {
 175           my $value = $code->(@_);
 176           warn "Coercion returned undef!"
 177               unless defined $value;
 178           return $value;
 179       };
 180   }
 181
 182   1;
 183
 184 This class wraps the coercion generator (e.g., C<to_Int()>) and warns
 185 if a coercion returned an undefined value. You can wrap any library
 186 with this:
 187
 188   package Foo;
 189   use strict;
 190   use MyWrapper MyLibrary => [qw( Foo Bar )],
 191                 Moose     => [qw( Str Int )];
 192
 193   ...
 194   1;
 195
 196 The C<Moose> library name is a special shortcut for
 197 L<MooseX::Types::Moose>.
 198
 199 =head2 Generator methods you can overload
 200
 201 =over 4
 202
 203 =item type_export_generator( $short, $full )
 204
 205 Creates a closure returning the type's L<Moose::Meta::TypeConstraint>
 206 object.
 207
 208 =item check_export_generator( $short, $full, $undef_message )
 209
 210 This creates the closure used to test if a value is valid for this type.
 211
 212 =item coercion_export_generator( $short, $full, $undef_message )
 213
 214 This is the closure that's doing coercions.
 215
 216 =back
 217
 218 =head2 Provided Parameters
 219
 220 =over 4
 221
 222 =item $short
 223
 224 The short, exported name of the type.
 225
 226 =item $full
 227
 228 The fully qualified name of this type as L<Moose> knows it.
 229
 230 =item $undef_message
 231
 232 A message that will be thrown when type functionality is used but the
 233 type does not yet exist.
 234
 235 =back
 236
 237 =head1 METHODS
 238
 239 =head2 import
 240
 241 Installs the L<MooseX::Types::Base> class into the caller and
 242 exports types according to the specification described in
 243 L</"LIBRARY DEFINITION">. This will continue to
 244 L<Moose::Util::TypeConstraints>' C<import> method to export helper
 245 functions you will need to declare your types.
 246
 247 =cut
 248
 249 sub import {
 250     my ($class, %args) = @_;
 251     my  $callee = caller;
 252
 253     # inject base class into new library
 254     {   no strict 'refs';
 255         unshift @{ $callee . '::ISA' }, 'MooseX::Types::Base';
 256     }
 257
 258     # generate predeclared type helpers
 259     if (my @orig_declare = @{ $args{ -declare } || [] }) {
 260         my ($tags, $declare) = filter_tags @orig_declare;
 261
 262         for my $type (@$declare) {
 263             $callee->add_type($type);
 264             $callee->export_type_into(
 265                 $callee, $type,
 266                 sprintf($UndefMsg, $type, $callee),
 267                 -full => 1,
 268             );
 269         }
 270     }
 271
 272     # run type constraints import
 273     return Moose::Util::TypeConstraints->import({ into => $callee });
 274 }
 275
 276 =head2 type_export_generator
 277
 278 Generate a type export, e.g. C<Int()>. This will return either a
 279 L<Moose::Meta::TypeConstraint> object, or alternatively a
 280 L<MooseX::Types::UndefinedType> object if the type was not
 281 yet defined.
 282
 283 =cut
 284
 285 sub type_export_generator {
 286     my ($class, $type, $full) = @_;
 287     return sub {
 288         return find_type_constraint($full)
 289             || MooseX::Types::UndefinedType->new($full);
 290     };
 291 }
 292
 293 =head2 coercion_export_generator
 294
 295 This generates a coercion handler function, e.g. C<to_Int($value)>.
 296
 297 =cut
 298
 299 sub coercion_export_generator {
 300     my ($class, $type, $full, $undef_msg) = @_;
 301     return sub {
 302         my ($value) = @_;
 303
 304         # we need a type object
 305         my $tobj = find_type_constraint($full) or croak $undef_msg;
 306         my $return = $tobj->coerce($value);
 307
 308         # non-successful coercion returns false
 309         return unless $tobj->check($return);
 310
 311         return $return;
 312     }
 313 }
 314
 315 =head2 check_export_generator
 316
 317 Generates a constraint check closure, e.g. C<is_Int($value)>.
 318
 319 =cut
 320
 321 sub check_export_generator {
 322     my ($class, $type, $full, $undef_msg) = @_;
 323     return sub {
 324         my ($value) = @_;
 325
 326         # we need a type object
 327         my $tobj = find_type_constraint($full) or croak $undef_msg;
 328
 329         return $tobj->check($value);
 330     }
 331 }
 332
 333 =head1 CAVEATS
 334
 335 A library makes the types quasi-unique by prefixing their names with (by
 336 default) the library package name. If you're only using the type handler
 337 functions provided by MooseX::Types, you shouldn't ever have to use
 338 a type's actual full name.
 339
 340 =head1 SEE ALSO
 341
 342 L<Moose>, L<Moose::Util::TypeConstraints>, L<MooseX::Types::Moose>
 343
 344 =head1 AUTHOR AND COPYRIGHT
 345
 346 Robert 'phaylon' Sedlacek C<E<lt>rs@474.atE<gt>>, with many thanks to
 347 the C<#moose> cabal on C<irc.perl.org>.
 348
 349 =head1 LICENSE
 350
 351 This program is free software; you can redistribute it and/or modify
 352 it under the same terms as perl itself.
 353
 354 =cut
 355
 356 1;