use 5.008;
-our $VERSION = '0.01';
+our $VERSION = '0.02';
$VERSION = eval $VERSION;
use Moose::Util::TypeConstraints;
The follow is example usage.
+ package Test::MooseX::Types::Parameterizable::Synopsis;
+
use Moose;
use MooseX::Types::Parameterizable qw(Parameterizable);
- use MooseX::Types::Moose qw(Str Int);
+ use MooseX::Types::Moose qw(Str Int ArrayRef);
use MooseX::Types -declare=>[qw(Varchar)];
+ ## Create a type constraint that is a string but parameterizes an integer
+ ## that is used as a maximum length constraint on that string, similar to
+ ## a SQL Varchar database type.
+
subtype Varchar,
as Parameterizable[Str,Int],
where {
my($string, $int) = @_;
$int >= length($string) ? 1:0;
},
- message {
- "'$_' is too long"
+ message { "'$_' is too long" };
+
+ ## Coerce an ArrayRef to a string via concatenation.
+
+ coerce Varchar,
+ from ArrayRef,
+ via {
+ my ($arrayref, $int) = @_;
+ join('', @$arrayref);
};
- has varchar_five => (isa=>Varchar[5], is=>'ro');
- has varchar_ten => (isa=>Varchar[10], is=>'ro');
+ has 'varchar_five' => (isa=>Varchar[5], is=>'ro', coerce=>1);
+ has 'varchar_ten' => (isa=>Varchar[10], is=>'ro');
- ## This works fine
+ ## Object created since attributes are valid
my $object1 = __PACKAGE__->new(
varchar_five => '1234',
varchar_ten => '123456789',
);
- ## This explodes with a type constraint error
+ ## Dies with an invalid constraint for 'varchar_five'
my $object2 = __PACKAGE__->new(
- varchar_five => '12345678', ## Too long string
+ varchar_five => '12345678', ## too long!
varchar_ten => '123456789',
);
+ ## varchar_five coerces as expected
+ my $object3 = __PACKAGE__->new(
+ varchar_five => [qw/aa bb/], ## coerces to "aabb"
+ varchar_ten => '123456789',
+ );
+
See t/05-pod-examples.t for runnable versions of all POD code
=head1 DESCRIPTION
-A L<MooseX::Types> library for creating parameterizable types. A parameterizable type
-constraint for all intents and uses is a subclass of a parent type, but adds a
-secondary type parameter which is available to constraint callbacks (such as
-inside the 'where' clause) or in the coercions.
+A L<MooseX::Types> library for creating parameterizable types. A parameterizable
+type constraint for all intents and uses is a subclass of a parent type, but
+adds additional type parameters which are available to constraint callbacks
+(such as inside the 'where' clause of a type constraint definition) or in the
+coercions.
-This allows you to create a type that has additional runtime advice, such as a
-set of numbers within which another number must be unique, or allowable ranges
-for a integer, such as in:
+If you have L<Moose> experience, you probably are familiar with the builtin
+parameterizable type constraints 'ArrayRef' and 'HashRef'. This type constraint
+lets you generate your own versions of parameterized constraints that work
+similarly. See L<Moose::Util::TypeConstraints> for more.
+
+Using this type constraint, you can generate new type constraints that have
+additional runtime advice, such as being able to specify maximum and minimum
+values for an Int (integer) type constraint:
subtype Range,
as Dict[max=>Int, min=>Int],
RangedInt([{min=>10,max=>100}])->check(50); ## OK
RangedInt([{min=>50, max=>75}])->check(99); ## Not OK, 99 exceeds max
-
-This throws a hard Moose exception. You'll need to capture it in an eval or
-related exception catching system (see L<TryCatch> or <Try::Tiny>.)
+
+The type parameter must be valid against the type constraint given. If you pass
+an invalid value this throws a hard Moose exception. You'll need to capture it
+in an eval or related exception catching system (see L<TryCatch> or <Try::Tiny>.)
+For example the following would throw a hard error (and not just return false)
RangedInt([{min=>99, max=>10}])->check(10); ## Not OK, not a valid Range!
conciseness of your type constraint declarations. An exception wil be thrown if
your type parameters don't match the required reference type.
-Also not that if you 'chain' parameterization results with a method call like:
+Also note that if you 'chain' parameterization results with a method call like:
TypeConstraint([$ob])->method;
You need to have the "(...)" around the ArrayRef in the Type Constraint
-parameters. This seems to have something to do with the precendent level of
-"->". Patches or thoughts welcomed. You only need to do this in the above
-case which I imagine is not a very common case.
+parameters. You can skip the wrapping parenthesis in the most common cases,
+such as when you use the type constraint in the options section of a L<Moose>
+attribute declaration, or when defining type libraries.
==head2 Subtyping a Parameterizable type constraints
shift >= 0;
};
-Or you could have done the following instead:
+In this case you'd now have a parameterizable type constraint called which
+would work like:
+
+ Test::More::ok PositiveRangedInt([{min=>-10, max=>75}])->check(5);
+ Test::More::ok !PositiveRangedInt([{min=>-10, max=>75}])->check(-5);
+
+Of course the above is somewhat counter-intuitive to the reader, since we have
+defined our 'RangedInt' in such as way as to let you declare negative ranges.
+For the moment each type constraint rule is apply without knowledge of any
+other rule, nor can a rule 'inform' existing rules. This is a limitation of
+the current system. However, you could instead do the following:
+
## Subtype of Int for positive numbers
subtype PositiveInt,
subtype PositiveRangedInt,
as RangedInt[PositiveRange];
+This would constrain values in the same way as the previous type constraint but
+have the bonus that you'd throw a hard exception if you try to use an incorrect
+range:
+
+ Test::More::ok PositiveRangedInt([{min=>10, max=>75}])->check(15); ## OK
+ Test::More::ok !PositiveRangedInt([{min=>-10, max=>75}])->check(-5); ## Dies
+
Notice how re-parameterizing the parameterizable type 'RangedInt' works slightly
differently from re-parameterizing 'PositiveRange' Although it initially takes
two type constraint values to declare a parameterizable type, should you wish to
-later re-parameterize it, you only use a subtype of the second type parameter
-(the parameterizable type constraint) since the first type constraint sets the parent
-type for the parameterizable type. In other words, given the example above, a type
-constraint of 'RangedInt' would have a parent of 'Int', not 'Parameterizable' and for
-all intends and uses you could stick it wherever you'd need an Int.
-
- subtype NameAge,
- as Tuple[Str, Int];
-
- ## re-parameterized subtypes of NameAge containing a Parameterizable Int
- subtype NameBetween18and35Age,
- as NameAge[
- Str,
- PositiveRangedInt[min=>18,max=>35],
- ];
-
-One caveat is that you can't stick an unparameterized parameterizable type inside a
-structure, such as L<MooseX::Types::Structured> since that would require the
-ability to convert a 'containing' type constraint into a parameterizable type, which
-is a capacity we current don't have.
+later re-parameterize it, you only use a subtype of the extra type parameter
+(the parameterizable type constraints) since the first type constraint sets the
+parent type for the parameterizable type.
+
+In other words, given the example above, a type constraint of 'RangedInt' would
+have a parent of 'Int', not 'Parameterizable' and for all intends and uses you
+could stick it wherever you'd need an Int.
=head2 Coercions
Parameterizable types have some limited support for coercions. Several things must
be kept in mind. The first is that the coercion targets the type constraint
-which is being made parameterizable, Not the parameterizable type. So for example if you
+which is being made parameterizable, Not the parameterized type. So for example if you
create a Parameterizable type like:
subtype RequiredAgeInYears,
=head2 Recursion
- TBD
+ TBD - Need more tests.
=head1 TYPE CONSTRAINTS