1 package MooseX::Types::Parameterizable;
6 $VERSION = eval $VERSION;
8 use Moose::Util::TypeConstraints;
9 use MooseX::Meta::TypeConstraint::Parameterizable;
10 use MooseX::Types -declare => [qw(Parameterizable)];
14 MooseX::Types::Parameterizable - Create your own Parameterizable Types.
18 The follow is example usage.
21 use MooseX::Types::Parameterizable qw(Parameterizable);
22 use MooseX::Types::Moose qw(Str Int);
23 use MooseX::Types -declare=>[qw(Varchar)];
26 as Parameterizable[Str,Int],
28 my($string, $int) = @_;
29 $int >= length($string) ? 1:0;
35 has varchar_five => (isa=>Varchar[5], is=>'ro');
36 has varchar_ten => (isa=>Varchar[10], is=>'ro');
39 my $object1 = __PACKAGE__->new(
40 varchar_five => '1234',
41 varchar_ten => '123456789',
44 ## This explodes with a type constraint error
45 my $object2 = __PACKAGE__->new(
46 varchar_five => '12345678', ## Too long string
47 varchar_ten => '123456789',
50 See t/05-pod-examples.t for runnable versions of all POD code
54 A L<MooseX::Types> library for creating parameterizable types. A parameterizable type
55 constraint for all intents and uses is a subclass of a parent type, but adds a
56 secondary type parameter which is available to constraint callbacks (such as
57 inside the 'where' clause) or in the coercions.
59 This allows you to create a type that has additional runtime advice, such as a
60 set of numbers within which another number must be unique, or allowable ranges
61 for a integer, such as in:
64 as Dict[max=>Int, min=>Int],
67 return $range->{max} > $range->{min};
71 as Parameterizable[Int, Range],
73 my ($value, $range) = @_;
74 return ($value >= $range->{min} &&
75 $value <= $range->{max});
78 RangedInt([{min=>10,max=>100}])->check(50); ## OK
79 RangedInt([{min=>50, max=>75}])->check(99); ## Not OK, 99 exceeds max
81 This throws a hard Moose exception. You'll need to capture it in an eval or
82 related exception catching system (see L<TryCatch> or <Try::Tiny>.)
84 RangedInt([{min=>99, max=>10}])->check(10); ## Not OK, not a valid Range!
86 If you can't accept a hard exception here, you'll need to test the constraining
89 my $range = {min=>99, max=>10};
90 if(my $err = Range->validate($range)) {
93 RangedInt($range)->check(99);
96 Please note that for ArrayRef or HashRef parameterizable type constraints, as in the
97 example above, as a convenience we automatically ref the incoming type
98 parameters, so that the above could also be written as:
100 RangedInt([min=>10,max=>100])->check(50); ## OK
101 RangedInt([min=>50, max=>75])->check(99); ## Not OK, 99 exceeds max
102 RangedInt([min=>99, max=>10])->check(10); ## Exception, not a valid Range!
104 This is the preferred syntax, as it improve readability and adds to the
105 conciseness of your type constraint declarations. An exception wil be thrown if
106 your type parameters don't match the required reference type.
108 Also not that if you 'chain' parameterization results with a method call like:
110 TypeConstraint([$ob])->method;
112 You need to have the "(...)" around the ArrayRef in the Type Constraint
113 parameters. This seems to have something to do with the precendent level of
114 "->". Patches or thoughts welcomed. You only need to do this in the above
115 case which I imagine is not a very common case.
117 ==head2 Subtyping a Parameterizable type constraints
119 When subclassing a parameterizable type you must be careful to match either the
120 required type parameter type constraint, or if re-parameterizing, the new
121 type constraints are a subtype of the parent. For example:
124 as Parameterizable[Int, Range],
126 my ($value, $range) = @_;
127 return ($value >= $range->{min} &&
128 $value =< $range->{max});
131 Example subtype with additional constraints:
133 subtype PositiveRangedInt,
139 Or you could have done the following instead:
141 ## Subtype of Int for positive numbers
145 my ($value, $range) = @_;
149 ## subtype Range to re-parameterize Range with subtypes
150 subtype PositiveRange,
151 as Range[max=>PositiveInt, min=>PositiveInt];
153 ## create subtype via reparameterizing
154 subtype PositiveRangedInt,
155 as RangedInt[PositiveRange];
157 Notice how re-parameterizing the parameterizable type 'RangedInt' works slightly
158 differently from re-parameterizing 'PositiveRange' Although it initially takes
159 two type constraint values to declare a parameterizable type, should you wish to
160 later re-parameterize it, you only use a subtype of the second type parameter
161 (the parameterizable type constraint) since the first type constraint sets the parent
162 type for the parameterizable type. In other words, given the example above, a type
163 constraint of 'RangedInt' would have a parent of 'Int', not 'Parameterizable' and for
164 all intends and uses you could stick it wherever you'd need an Int.
169 ## re-parameterized subtypes of NameAge containing a Parameterizable Int
170 subtype NameBetween18and35Age,
173 PositiveRangedInt[min=>18,max=>35],
176 One caveat is that you can't stick an unparameterized parameterizable type inside a
177 structure, such as L<MooseX::Types::Structured> since that would require the
178 ability to convert a 'containing' type constraint into a parameterizable type, which
179 is a capacity we current don't have.
183 Parameterizable types have some limited support for coercions. Several things must
184 be kept in mind. The first is that the coercion targets the type constraint
185 which is being made parameterizable, Not the parameterizable type. So for example if you
186 create a Parameterizable type like:
188 subtype RequiredAgeInYears,
191 subtype PersonOverAge,
192 as Parameterizable[Person, RequiredAgeInYears]
194 my ($person, $required_years_old) = @_;
195 return $person->years_old > $required_years_old;
198 This would validate the following:
200 my $person = Person->new(age=>35);
201 PersonOverAge([18])->check($person);
203 You can then apply the following coercion
205 coerce PersonOverAge,
207 via {Person->new(%$_)},
209 via {Person->new(age=>$_)};
211 This coercion would then apply to all the following:
213 PersonOverAge([18])->check(30); ## via the Int coercion
214 PersonOverAge([18])->check({age=>50}); ## via the Dict coercion
216 However, you are not allowed to place coercions on parameterizable types that have
217 had their constraining value filled, nor subtypes of such. For example:
219 coerce PersonOverAge[18],
223 That would generate a hard exception. This is a limitation for now until I can
224 devise a smarter way to cache the generated type constraints. However, I doubt
225 it will be a significant limitation, since the general use case is supported.
227 Lastly, the constraining value is available in the coercion in much the same way
228 it is available to the constraint.
230 ## Create a type constraint where a Person must be in the set
232 as Parameterizable[Person, PersonSet],
234 my ($person, $person_set) = @_;
235 $person_set->find($person);
241 my ($hashref, $person_set) = @_;
242 return $person_set->create($hash_ref);
249 =head1 TYPE CONSTRAINTS
251 This type library defines the following constraints.
253 =head2 Parameterizable[ParentTypeConstraint, ParameterizableValueTypeConstraint]
255 Create a subtype of ParentTypeConstraint with a dependency on a value that can
256 pass the ParameterizableValueTypeConstraint. If ParameterizableValueTypeConstraint is empty
257 we default to the 'Any' type constraint (see L<Moose::Util::TypeConstraints>).
259 This creates a type constraint which must be further parameterized at later time
260 before it can be used to ->check or ->validate a value. Attempting to do so
261 will cause an exception.
265 Moose::Util::TypeConstraints::get_type_constraint_registry->add_type_constraint(
266 MooseX::Meta::TypeConstraint::Parameterizable->new(
267 name => 'MooseX::Types::Parameterizable::Parameterizable',
268 parent => find_type_constraint('Any'),
269 constraint => sub {1},
275 John Napiorkowski, C<< <jjnapiork@cpan.org> >>
277 =head1 COPYRIGHT & LICENSE
279 This program is free software; you can redistribute it and/or modify
280 it under the same terms as Perl itself.