lib/MooseX/TypeLibrary.pm

   1 package MooseX::TypeLibrary;
   2
   3 =head1 NAME
   4
   5 MooseX::TypeLibrary - 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::TypeLibrary::Base;
  15 use MooseX::TypeLibrary::Util           qw( filter_tags );
  16 use MooseX::TypeLibrary::UndefinedType;
  17 use Sub::Install                        qw( install_sub );
  18 use namespace::clean;
  19
  20 our $VERSION = 0.01;
  21
  22 my $UndefMsg = q{Action for type '%s' not yet defined in library '%s'};
  23
  24 =head1 SYNOPSIS
  25
  26   #
  27   # Library Definition
  28   #
  29   package MyLibrary;
  30   use strict;
  31
  32   # predeclare our own types
  33   use MooseX::TypeLibrary
  34       -declare => [qw( PositiveInt NegativeInt )];
  35
  36   # import builtin types
  37   use MooseX::TypeLibrary::Moose 'Int';
  38
  39   # type definition
  40   subtype PositiveInt,
  41       as Int,
  42       where { $_ > 0 },
  43       message { "Int is not larger than 0" };
  44
  45   subtype NegativeInt,
  46       as Int,
  47       where { $_ < 0 },
  48       message { "Int is not smaller than 0" };
  49
  50   # type coercion
  51   coerce PositiveInt,
  52       from Int,
  53           via { 1 };
  54
  55   1;
  56
  57   #
  58   # Usage
  59   #
  60   package Foo;
  61   use Moose;
  62   use MyLibrary qw( PositiveInt NegativeInt );
  63
  64   # use the exported constants as type names
  65   has 'bar',
  66       isa    => PositiveInt,
  67       is     => 'rw';
  68   has 'baz',
  69       isa    => NegativeInt,
  70       is     => 'rw';
  71
  72   sub quux {
  73       my ($self, $value);
  74
  75       # test the value
  76       print "positive\n" if is_PositiveInt($value);
  77       print "negative\n" if is_NegativeInt($value);
  78
  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";
  82   }
  83
  84   1;
  85
  86 =head1 DESCRIPTION
  87
  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.
  91
  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.
  95
  96 This module will also provide you with some helper functions to make it
  97 easier to use Moose types in your code.
  98
  99 =head1 TYPE HANDLER FUNCTIONS
 100
 101 =head2 $type
 102
 103 A constant with the name of your type. It contains the type's fully
 104 qualified name. Takes no value, as all constants.
 105
 106 =head2 is_$type
 107
 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.
 110
 111 =head2 to_$type
 112
 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.
 115
 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.
 119
 120 =head1 LIBRARY DEFINITION
 121
 122 A MooseX::TypeLibrary 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.
 125
 126 The only thing a library is required to do is
 127
 128   use MooseX::TypeLibrary -declare => \@types;
 129
 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
 135 types.
 136
 137 If you want to use Moose' built-in types (e.g. for subtyping) you will
 138 want to
 139
 140   use MooseX::TypeLibrary::Moose @types;
 141
 142 to import the helpers from the shipped L<MooseX::TypeLibrary::Moose>
 143 library which can export all types that come with Moose.
 144
 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.
 147
 148 =head1 LIBRARY USAGE
 149
 150 You can import the L<"type helpers"|/"TYPE HANDLER FUNCTIONS"> of a
 151 library by C<use>ing it with a list of types to import as arguments. If
 152 you want all of them, use the C<:all> tag. For example:
 153
 154   use MyLibrary      ':all';
 155   use MyOtherLibrary qw( TypeA TypeB );
 156
 157 MooseX::TypeLibrary comes with a library of Moose' built-in types called
 158 L<MooseX::TypeLibrary::Moose>.
 159
 160 =head1 METHODS
 161
 162 =head2 import
 163
 164 Installs the L<MooseX::TypeLibrary::Base> class into the caller and
 165 exports types according to the specification described in
 166 L</"LIBRARY DEFINITION">. This will continue to
 167 L<Moose::Util::TypeConstraints>' C<import> method to export helper
 168 functions you will need to declare your types.
 169
 170 =cut
 171
 172 sub import {
 173     my ($class, %args) = @_;
 174     my  $callee = caller;
 175
 176     # inject base class into new library
 177     {   no strict 'refs';
 178         unshift @{ $callee . '::ISA' }, 'MooseX::TypeLibrary::Base';
 179     }
 180
 181     # generate predeclared type helpers
 182     if (my @orig_declare = @{ $args{ -declare } || [] }) {
 183         my ($tags, $declare) = filter_tags @orig_declare;
 184
 185         for my $type (@$declare) {
 186             $callee->add_type($type);
 187             $callee->export_type_into(
 188                 $callee, $type,
 189                 sprintf($UndefMsg, $type, $callee),
 190                 -full => 1,
 191             );
 192         }
 193     }
 194
 195     # run type constraints import
 196     return uplevel 1,
 197         Moose::Util::TypeConstraints->can('import'),
 198         'Moose::Util::TypeConstraints';
 199 }
 200
 201 =head2 type_export_generator
 202
 203 Generate a type export, e.g. C<Int()>. This will return either a
 204 L<Moose::Meta::TypeConstraint> object, or alternatively a
 205 L<MooseX::TypeLibrary::UndefinedType> object if the type was not
 206 yet defined.
 207
 208 =cut
 209
 210 sub type_export_generator {
 211     my ($class, $type, $full) = @_;
 212     return sub {
 213         return find_type_constraint($full)
 214             || MooseX::TypeLibrary::UndefinedType->new($full);
 215     };
 216 }
 217
 218 =head2 coercion_export_generator
 219
 220 This generates a coercion handler function, e.g. C<to_Int($value)>.
 221
 222 =cut
 223
 224 sub coercion_export_generator {
 225     my ($class, $type, $full, $undef_msg) = @_;
 226     return sub {
 227         my ($value) = @_;
 228
 229         # we need a type object
 230         my $tobj = find_type_constraint($full) or croak $undef_msg;
 231         my $return = $tobj->coerce($value);
 232
 233         # non-successful coercion returns false
 234         return unless $tobj->check($return);
 235
 236         return $return;
 237     }
 238 }
 239
 240 =head2 check_export_generator
 241
 242 Generates a constraint check closure, e.g. C<is_Int($value)>.
 243
 244 =cut
 245
 246 sub check_export_generator {
 247     my ($class, $type, $full, $undef_msg) = @_;
 248     return sub {
 249         my ($value) = @_;
 250
 251         # we need a type object
 252         my $tobj = find_type_constraint($full) or croak $undef_msg;
 253
 254         return $tobj->check($value);
 255     }
 256 }
 257
 258 =head1 CAVEATS
 259
 260 A library makes the types quasi-unique by prefixing their names with (by
 261 default) the library package name. If you're only using the type handler
 262 functions provided by MooseX::TypeLibrary, you shouldn't ever have to use
 263 a type's actual full name.
 264
 265 =head1 SEE ALSO
 266
 267 L<Moose>, L<Moose::Util::TypeConstraints>, L<MooseX::TypeLibrary::Moose>
 268
 269 =head1 AUTHOR AND COPYRIGHT
 270
 271 Robert 'phaylon' Sedlacek C<E<lt>rs@474.atE<gt>>, with many thanks to
 272 the C<#moose> cabal on C<irc.perl.org>.
 273
 274 =head1 LICENSE
 275
 276 This program is free software; you can redistribute it and/or modify
 277 it under the same terms as perl itself.
 278
 279 =cut
 280
 281 1;