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 Sub::Install    qw( install_sub );
  16 use namespace::clean;
  17
  18 our $VERSION = 0.01;
  19
  20 my $UndefMsg = q{Action for type '%s' not yet defined in library '%s'};
  21
  22 =head1 SYNOPSIS
  23
  24   #
  25   # Library Definition
  26   #
  27   package MyLibrary;
  28   use strict;
  29
  30   # predeclare our own types
  31   use MooseX::TypeLibrary
  32       -declare => [qw( PositiveInt NegativeInt )];
  33
  34   # import builtin types
  35   use MooseX::TypeLibrary::Moose 'Int';
  36
  37   # type definition
  38   subtype PositiveInt,
  39       as Int,
  40       where { $_ > 0 },
  41       message { "Int is not larger than 0" };
  42
  43   subtype NegativeInt,
  44       as Int,
  45       where { $_ < 0 },
  46       message { "Int is not smaller than 0" };
  47
  48   # type coercion
  49   coerce PositiveInt,
  50       from Int,
  51           via { 1 };
  52
  53   1;
  54
  55   #
  56   # Usage
  57   #
  58   package Foo;
  59   use Moose;
  60   use MyLibrary qw( PositiveInt NegativeInt );
  61
  62   # use the exported constants as type names
  63   has 'bar',
  64       isa    => PositiveInt,
  65       is     => 'rw';
  66   has 'baz',
  67       isa    => NegativeInt,
  68       is     => 'rw';
  69
  70   sub quux {
  71       my ($self, $value);
  72
  73       # test the value
  74       print "positive\n" if is_PositiveInt($value);
  75       print "negative\n" if is_NegativeInt($value);
  76
  77       # coerce the value, NegativeInt doesn't have a coercion
  78       # helper, since it didn't define any coercions.
  79       $value = to_PositiveInt($value) or die "Cannot coerce";
  80   }
  81
  82   1;
  83
  84 =head1 DESCRIPTION
  85
  86 The types provided with L<Moose> are by design global. This package helps
  87 you to organise and selectively import your own and the built-in types in
  88 libraries. As a nice side effect, it catches typos at compile-time too.
  89
  90 However, the main reason for this module is to provide an easy way to not
  91 have conflicts with your type names, since the internal fully qualified
  92 names of the types will be prefixed with the library's name.
  93
  94 This module will also provide you with some helper functions to make it
  95 easier to use Moose types in your code.
  96
  97 =head1 TYPE HANDLER FUNCTIONS
  98
  99 =head2 $type
 100
 101 A constant with the name of your type. It contains the type's fully
 102 qualified name. Takes no value, as all constants.
 103
 104 =head2 is_$type
 105
 106 This handler takes a value and tests if it is a valid value for this
 107 C<$type>. It will return true or false.
 108
 109 =head2 to_$type
 110
 111 A handler that will take a value and coerce it into the C<$type>. It will
 112 return a false value if the type could not be coerced.
 113
 114 B<Important Note>: This handler will only be exported for types that can
 115 do type coercion. This has the advantage that a coercion to a type that
 116 cannot hasn't defined any coercions will lead to a compile-time error.
 117
 118 =head1 LIBRARY DEFINITION
 119
 120 A MooseX::TypeLibrary is just a normal Perl module. Unlike Moose
 121 itself, it does not install C<use strict> and C<use warnings> in your
 122 class by default, so this is up to you.
 123
 124 The only thing a library is required to do is
 125
 126   use MooseX::TypeLibrary -declare => \@types;
 127
 128 with C<@types> being a list of types you wish to define in this library.
 129 This line will install a proper base class in your package as well as the
 130 full set of L<handlers|/"TYPE HANDLER FUNCTIONS"> for your declared
 131 types. It will then hand control over to L<Moose::Util::TypeConstraints>'
 132 C<import> method to export the functions you will need to declare your
 133 types.
 134
 135 If you want to use Moose' built-in types (e.g. for subtyping) you will
 136 want to
 137
 138   use MooseX::TypeLibrary::Moose @types;
 139
 140 to import the helpers from the shipped L<MooseX::TypeLibrary::Moose>
 141 library which can export all types that come with Moose.
 142
 143 You will have to define coercions for your types or your library won't
 144 export a L</to_$type> coercion helper for it.
 145
 146 =head1 LIBRARY USAGE
 147
 148 You can import the L<"type helpers"|/"TYPE HANDLER FUNCTIONS"> of a
 149 library by C<use>ing it with a list of types to import as arguments. If
 150 you want all of them, use the C<:all> tag. For example:
 151
 152   use MyLibrary      ':all';
 153   use MyOtherLibrary qw( TypeA TypeB );
 154
 155 MooseX::TypeLibrary comes with a library of Moose' built-in types called
 156 L<MooseX::TypeLibrary::Moose>.
 157
 158 =head1 METHODS
 159
 160 =head2 import
 161
 162 =cut
 163
 164 sub import {
 165     my ($class, %args) = @_;
 166     my  $callee = caller;
 167
 168     # inject base class into new library
 169     {   no strict 'refs';
 170         unshift @{ $callee . '::ISA' }, 'MooseX::TypeLibrary::Base';
 171     }
 172
 173     # generate predeclared type helpers
 174     if (my @declare = @{ $args{ -declare } || [] }) {
 175         for my $type (@declare) {
 176             $callee->add_type($type);
 177             $callee->export_type_into(
 178                 $callee, $type,
 179                 sprintf($UndefMsg, $type, $callee),
 180                 -full => 1,
 181             );
 182         }
 183     }
 184
 185     # run type constraints import
 186     return uplevel 1,
 187         Moose::Util::TypeConstraints->can('import'),
 188         'Moose::Util::TypeConstraints';
 189 }
 190
 191 =head2 type_export_generator
 192
 193 =cut
 194
 195 sub type_export_generator {
 196     my ($class, $type, $full) = @_;
 197     return sub { $full };
 198 }
 199
 200 =head2 coercion_export_generator
 201
 202 =cut
 203
 204 sub coercion_export_generator {
 205     my ($class, $type, $full, $undef_msg) = @_;
 206     return sub {
 207         my ($value) = @_;
 208
 209         # we need a type object
 210         my $tobj = find_type_constraint($full) or croak $undef_msg;
 211         my $return = $tobj->coerce($value);
 212
 213         # non-successful coercion returns false
 214         return unless $tobj->check($return);
 215
 216         return $return;
 217     }
 218 }
 219
 220 =head2 check_export_generator
 221
 222 =cut
 223
 224 sub check_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
 232         return $tobj->check($value);
 233     }
 234 }
 235
 236 =head1 SEE ALSO
 237
 238 L<Moose>, L<Moose::Util::TypeConstraints>, L<MooseX::TypeLibrary::Moose>
 239
 240 =head1 AUTHOR AND COPYRIGHT
 241
 242 Robert 'phaylon' Sedlacek C<E<lt>rs@474.atE<gt>>, with many thanks to
 243 the C<#moose> cabal on C<irc.perl.org>.
 244
 245 =head1 LICENSE
 246
 247 This program is free software; you can redistribute it and/or modify
 248 it under the same terms as perl itself.
 249
 250 =cut
 251
 252 1;