1 package MooseX::Parameterizable::Types;
6 $VERSION = eval $VERSION;
8 use Moose::Util::TypeConstraints;
9 use MooseX::Parameterizable::Meta::TypeConstraint::Parameterizable;
10 use MooseX::Types -declare => [qw(Parameterizable)];
14 MooseX::Parameterizable::Types - Create your own Parameterizable Types.
18 Within your L<MooseX::Types> declared library module:
20 use MooseX::Parameterizable::Types qw(Parameterizable);
23 as class_type("Set::Scalar");
26 as Parameterizable[Int, Set],
29 return !$set->has($int);
36 return !grep {$_ <0 } $set->members;
39 subtype PositiveUniqueInt,
40 as UniqueInt[PositiveSet];
42 my $set = Set::Scalar->new(1,2,3);
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)
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)
52 my $negative_set = Set::Scalar->new(-1,-2,-3);
54 UniqueInt([$negative_set])->check(100); ## Throws exception
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.
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:
68 as Dict[max=>Int, min=>Int],
71 return $range->{max} > $range->{min};
75 as Parameterizable[Int, Range],
77 my ($value, $range) = @_;
78 return ($value >= $range->{min} &&
79 $value <= $range->{max});
82 RangedInt([{min=>10,max=>100}])->check(50); ## OK
83 RangedInt([{min=>50, max=>75}])->check(99); ## Not OK, 99 exceeds max
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>).
88 RangedInt([{min=>99, max=>10}])->check(10); ## Not OK, not a valid Range!
90 If you can't accept a hard exception here, you'll need to test the constraining
93 my $range = {min=>99, max=>10};
94 if(my $err = Range->validate($range)) {
97 RangedInt($range)->check(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:
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!
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.
112 Also not that if you 'chain' parameterization results with a method call like:
114 TypeConstraint([$ob])->method;
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.
121 ==head2 Subtyping a Parameterizable type constraints
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:
128 as Parameterizable[Int, Range],
130 my ($value, $range) = @_;
131 return ($value >= $range->{min} &&
132 $value =< $range->{max});
135 Example subtype with additional constraints:
137 subtype PositiveRangedInt,
143 Or you could have done the following instead:
145 ## Subtype of Int for positive numbers
149 my ($value, $range) = @_;
153 ## subtype Range to re-parameterize Range with subtypes
154 subtype PositiveRange,
155 as Range[max=>PositiveInt, min=>PositiveInt];
157 ## create subtype via reparameterizing
158 subtype PositiveRangedInt,
159 as RangedInt[PositiveRange];
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.
173 ## re-parameterized subtypes of NameAge containing a Parameterizable Int
174 subtype NameBetween18and35Age,
177 PositiveRangedInt[min=>18,max=>35],
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.
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:
192 subtype RequiredAgeInYears,
195 subtype PersonOverAge,
196 as Parameterizable[Person, RequiredAgeInYears]
198 my ($person, $required_years_old) = @_;
199 return $person->years_old > $required_years_old;
202 This would validate the following:
204 my $person = Person->new(age=>35);
205 PersonOverAge([18])->check($person);
207 You can then apply the following coercion
209 coerce PersonOverAge,
211 via {Person->new(%$_)},
213 via {Person->new(age=>$_)};
215 This coercion would then apply to all the following:
217 PersonOverAge([18])->check(30); ## via the Int coercion
218 PersonOverAge([18])->check({age=>50}); ## via the Dict coercion
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:
223 coerce PersonOverAge[18],
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.
231 Lastly, the constraining value is available in the coercion in much the same way
232 it is available to the constraint.
234 ## Create a type constraint where a Person must be in the set
236 as Parameterizable[Person, PersonSet],
238 my ($person, $person_set) = @_;
239 $person_set->find($person);
245 my ($hashref, $person_set) = @_;
246 return $person_set->create($hash_ref);
253 =head1 TYPE CONSTRAINTS
255 This type library defines the following constraints.
257 =head2 Parameterizable[ParentTypeConstraint, ParameterizableValueTypeConstraint]
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>).
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.
269 Moose::Util::TypeConstraints::get_type_constraint_registry->add_type_constraint(
270 MooseX::Parameterizable::Meta::TypeConstraint::Parameterizable->new(
271 name => 'MooseX::Parameterizable::Types::Parameterizable',
272 parent => find_type_constraint('Any'),
273 constraint => sub {1},
279 John Napiorkowski, C<< <jjnapiork@cpan.org> >>
281 =head1 COPYRIGHT & LICENSE
283 This program is free software; you can redistribute it and/or modify
284 it under the same terms as Perl itself.