lib/MooseX/Types/Parameterizable.pm

   1 package MooseX::Types::Parameterizable;
   2
   3 use 5.008;
   4
   5 our $VERSION   = '0.01';
   6 $VERSION = eval $VERSION;
   7
   8 use Moose::Util::TypeConstraints;
   9 use MooseX::Meta::TypeConstraint::Parameterizable;
  10 use MooseX::Types -declare => [qw(Parameterizable)];
  11
  12 =head1 NAME
  13
  14 MooseX::Types::Parameterizable - Create your own Parameterizable Types.
  15
  16 =head1 SYNOPSIS
  17
  18 Within your L<MooseX::Types> declared library module:
  19
  20     use MooseX::Types::Parameterizable qw(Parameterizable);
  21
  22     subtype Set,
  23         as class_type("Set::Scalar");
  24
  25     subtype UniqueInt,
  26         as Parameterizable[Int, Set],
  27         where {
  28             my ($int, $set) = @_;
  29             return !$set->has($int);
  30         };
  31
  32     subtype PositiveSet,
  33         as Set,
  34         where {
  35                 my ($set) = @_;
  36                 return !grep {$_ <0 } $set->members;
  37         };
  38
  39     subtype PositiveUniqueInt,
  40         as UniqueInt[PositiveSet];
  41
  42     my $set = Set::Scalar->new(1,2,3);
  43
  44     UniqueInt([$set])->check(100);  ## Okay, 100 isn't in (1,2,3)
  45     UniqueInt([$set])->check(-99);  ## Okay, -99 isn't in (1,2,3)
  46     UniqueInt([$set])->check(2);  ## Not OK, 2 is in (1,2,3)
  47
  48     PositiveUniqueInt([$set])->check(100);  ## Okay, 100 isn't in (1,2,3)
  49     PositiveUniqueInt([$set])->check(-99);  ## Not OK, -99 not Positive Int
  50     PositiveUniqueInt([$set])->check(2);  ## Not OK, 2 is in (1,2,3)
  51
  52     my $negative_set = Set::Scalar->new(-1,-2,-3);
  53
  54     UniqueInt([$negative_set])->check(100);  ## Throws exception
  55
  56 =head1 DESCRIPTION
  57
  58 A L<MooseX::Types> library for creating parameterizable types.  A parameterizable type
  59 constraint for all intents and uses is a subclass of a parent type, but adds a
  60 secondary type parameter which is available to constraint callbacks (such as
  61 inside the 'where' clause) or in the coercions.
  62
  63 This allows you to create a type that has additional runtime advice, such as a
  64 set of numbers within which another number must be unique, or allowable ranges
  65 for a integer, such as in:
  66
  67     subtype Range,
  68         as Dict[max=>Int, min=>Int],
  69         where {
  70                 my ($range) = @_;
  71                 return $range->{max} > $range->{min};
  72         };
  73
  74     subtype RangedInt,
  75         as Parameterizable[Int, Range],
  76         where {
  77                 my ($value, $range) = @_;
  78                 return ($value >= $range->{min} &&
  79                  $value <= $range->{max});
  80         };
  81
  82     RangedInt([{min=>10,max=>100}])->check(50); ## OK
  83     RangedInt([{min=>50, max=>75}])->check(99); ## Not OK, 99 exceeds max
  84
  85 This throws a hard Moose exception.  You'll need to capture it in an eval or
  86 related exception catching system (see L<TryCatch> or <Try::Tiny>.)
  87
  88     RangedInt([{min=>99, max=>10}])->check(10); ## Not OK, not a valid Range!
  89
  90 If you can't accept a hard exception here, you'll need to test the constraining
  91 values first, as in:
  92
  93     my $range = {min=>99, max=>10};
  94     if(my $err = Range->validate($range)) {
  95         ## Handle #$err
  96     } else {
  97         RangedInt($range)->check(99);
  98     }
  99
 100 Please note that for ArrayRef or HashRef parameterizable type constraints, as in the
 101 example above, as a convenience we automatically ref the incoming type
 102 parameters, so that the above could also be written as:
 103
 104     RangedInt([min=>10,max=>100])->check(50); ## OK
 105     RangedInt([min=>50, max=>75])->check(99); ## Not OK, 99 exceeds max
 106     RangedInt([min=>99, max=>10])->check(10); ## Exception, not a valid Range!
 107
 108 This is the preferred syntax, as it improve readability and adds to the
 109 conciseness of your type constraint declarations.  An exception wil be thrown if
 110 your type parameters don't match the required reference type.
 111
 112 Also not that if you 'chain' parameterization results with a method call like:
 113
 114     TypeConstraint([$ob])->method;
 115
 116 You need to have the "(...)" around the ArrayRef in the Type Constraint
 117 parameters.  This seems to have something to do with the precendent level of
 118 "->".  Patches or thoughts welcomed.  You only need to do this in the above
 119 case which I imagine is not a very common case.
 120
 121 ==head2 Subtyping a Parameterizable type constraints
 122
 123 When subclassing a parameterizable type you must be careful to match either the
 124 required type parameter type constraint, or if re-parameterizing, the new
 125 type constraints are a subtype of the parent.  For example:
 126
 127     subtype RangedInt,
 128         as Parameterizable[Int, Range],
 129         where {
 130                 my ($value, $range) = @_;
 131                 return ($value >= $range->{min} &&
 132                  $value =< $range->{max});
 133         };
 134
 135 Example subtype with additional constraints:
 136
 137     subtype PositiveRangedInt,
 138         as RangedInt,
 139         where {
 140                 shift >= 0;
 141         };
 142
 143 Or you could have done the following instead:
 144
 145     ## Subtype of Int for positive numbers
 146     subtype PositiveInt,
 147         as Int,
 148         where {
 149                 my ($value, $range) = @_;
 150                 return $value >= 0;
 151         };
 152
 153     ## subtype Range to re-parameterize Range with subtypes
 154     subtype PositiveRange,
 155         as Range[max=>PositiveInt, min=>PositiveInt];
 156
 157     ## create subtype via reparameterizing
 158     subtype PositiveRangedInt,
 159         as RangedInt[PositiveRange];
 160
 161 Notice how re-parameterizing the parameterizable type 'RangedInt' works slightly
 162 differently from re-parameterizing 'PositiveRange'  Although it initially takes
 163 two type constraint values to declare a parameterizable type, should you wish to
 164 later re-parameterize it, you only use a subtype of the second type parameter
 165 (the parameterizable type constraint) since the first type constraint sets the parent
 166 type for the parameterizable type.  In other words, given the example above, a type
 167 constraint of 'RangedInt' would have a parent of 'Int', not 'Parameterizable' and for
 168 all intends and uses you could stick it wherever you'd need an Int.
 169
 170     subtype NameAge,
 171         as Tuple[Str, Int];
 172
 173     ## re-parameterized subtypes of NameAge containing a Parameterizable Int
 174     subtype NameBetween18and35Age,
 175         as NameAge[
 176                 Str,
 177                 PositiveRangedInt[min=>18,max=>35],
 178         ];
 179
 180 One caveat is that you can't stick an unparameterized parameterizable type inside a
 181 structure, such as L<MooseX::Types::Structured> since that would require the
 182 ability to convert a 'containing' type constraint into a parameterizable type, which
 183 is a capacity we current don't have.
 184
 185 =head2 Coercions
 186
 187 Parameterizable types have some limited support for coercions.  Several things must
 188 be kept in mind.  The first is that the coercion targets the type constraint
 189 which is being made parameterizable, Not the parameterizable type.  So for example if you
 190 create a Parameterizable type like:
 191
 192     subtype RequiredAgeInYears,
 193       as Int;
 194
 195     subtype PersonOverAge,
 196       as Parameterizable[Person, RequiredAgeInYears]
 197       where {
 198         my ($person, $required_years_old) = @_;
 199         return $person->years_old > $required_years_old;
 200       }
 201
 202 This would validate the following:
 203
 204     my $person = Person->new(age=>35);
 205     PersonOverAge([18])->check($person);
 206
 207 You can then apply the following coercion
 208
 209     coerce PersonOverAge,
 210       from Dict[age=>int],
 211       via {Person->new(%$_)},
 212       from Int,
 213       via {Person->new(age=>$_)};
 214
 215 This coercion would then apply to all the following:
 216
 217     PersonOverAge([18])->check(30); ## via the Int coercion
 218     PersonOverAge([18])->check({age=>50}); ## via the Dict coercion
 219
 220 However, you are not allowed to place coercions on parameterizable types that have
 221 had their constraining value filled, nor subtypes of such.  For example:
 222
 223     coerce PersonOverAge[18],
 224       from DateTime,
 225       via {$_->years};
 226
 227 That would generate a hard exception.  This is a limitation for now until I can
 228 devise a smarter way to cache the generated type constraints.  However, I doubt
 229 it will be a significant limitation, since the general use case is supported.
 230
 231 Lastly, the constraining value is available in the coercion in much the same way
 232 it is available to the constraint.
 233
 234     ## Create a type constraint where a Person must be in the set
 235     subtype PersonInSet,
 236         as Parameterizable[Person, PersonSet],
 237         where {
 238                 my ($person, $person_set) = @_;
 239                 $person_set->find($person);
 240         }
 241
 242     coerce PersonInSet,
 243         from HashRef,
 244         via {
 245                 my ($hashref, $person_set) = @_;
 246                 return $person_set->create($hash_ref);
 247         };
 248
 249 =head2 Recursion
 250
 251     TBD
 252
 253 =head1 TYPE CONSTRAINTS
 254
 255 This type library defines the following constraints.
 256
 257 =head2 Parameterizable[ParentTypeConstraint, ParameterizableValueTypeConstraint]
 258
 259 Create a subtype of ParentTypeConstraint with a dependency on a value that can
 260 pass the ParameterizableValueTypeConstraint. If ParameterizableValueTypeConstraint is empty
 261 we default to the 'Any' type constraint (see L<Moose::Util::TypeConstraints>).
 262
 263 This creates a type constraint which must be further parameterized at later time
 264 before it can be used to ->check or ->validate a value.  Attempting to do so
 265 will cause an exception.
 266
 267 =cut
 268
 269 Moose::Util::TypeConstraints::get_type_constraint_registry->add_type_constraint(
 270     MooseX::Meta::TypeConstraint::Parameterizable->new(
 271         name => 'MooseX::Types::Parameterizable::Parameterizable',
 272         parent => find_type_constraint('Any'),
 273         constraint => sub {1},
 274     )
 275 );
 276
 277 =head1 AUTHOR
 278
 279 John Napiorkowski, C<< <jjnapiork@cpan.org> >>
 280
 281 =head1 COPYRIGHT & LICENSE
 282
 283 This program is free software; you can redistribute it and/or modify
 284 it under the same terms as Perl itself.
 285
 286 =cut
 287
 288 1;