[gitmo/MooseX-Dependent.git] / README

NAME
    MooseX::Types::Parameterizable - Create your own Parameterizable Types.

SYNOPSIS
    Within your MooseX::Types declared library module:

        use MooseX::Types::Parameterizable qw(Parameterizable);
        
            subtype Set,
                    as class_type("Set::Scalar");

        subtype UniqueInt,
            as Parameterizable[Int, Set],
            where {
                my ($int, $set) = @_;
                return !$set->has($int);
            };
                
            subtype PositiveSet,
                    as Set,
                    where {
                            my ($set) = @_;
                            return !grep {$_ <0 } $set->members;
                    };
                
        subtype PositiveUniqueInt,
            as UniqueInt[PositiveSet];
        
            my $set = Set::Scalar->new(1,2,3);

            UniqueInt([$set])->check(100);  ## Okay, 100 isn't in (1,2,3)
            UniqueInt([$set])->check(-99);  ## Okay, -99 isn't in (1,2,3)
            UniqueInt([$set])->check(2);  ## Not OK, 2 is in (1,2,3)
        
            PositiveUniqueInt([$set])->check(100);  ## Okay, 100 isn't in (1,2,3)
            PositiveUniqueInt([$set])->check(-99);  ## Not OK, -99 not Positive Int
            PositiveUniqueInt([$set])->check(2);  ## Not OK, 2 is in (1,2,3)
        
            my $negative_set = Set::Scalar->new(-1,-2,-3);
        
            UniqueInt([$negative_set])->check(100);  ## Throws exception

DESCRIPTION
    A 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.

    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:

            subtype Range,
                    as Dict[max=>Int, min=>Int],
                    where {
                            my ($range) = @_;
                            return $range->{max} > $range->{min};
                    };

            subtype RangedInt,
                    as Parameterizable[Int, Range],
                    where {
                            my ($value, $range) = @_;
                            return ($value >= $range->{min} &&
                             $value <= $range->{max});
                    };
                
            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 TryCatch).

            RangedInt([{min=>99, max=>10}])->check(10); ## Not OK, not a valid Range!

    If you can't accept a hard exception here, you'll need to test the
    constraining values first, as in:

            my $range = {min=>99, max=>10};
            if(my $err = Range->validate($range)) {
                    ## Handle #$err
            } else {
                    RangedInt($range)->check(99);
            }

    Please note that for ArrayRef or HashRef parameterizable type
    constraints, as in the example above, as a convenience we automatically
    ref the incoming type parameters, so that the above could also be
    written as:

            RangedInt([min=>10,max=>100])->check(50); ## OK
            RangedInt([min=>50, max=>75])->check(99); ## Not OK, 99 exceeds max
            RangedInt([min=>99, max=>10])->check(10); ## Exception, not a valid Range!

    This is the preferred syntax, as it improve readability and adds to the
    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:

            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.

    ==head2 Subtyping a Parameterizable type constraints

    When subclassing a parameterizable type you must be careful to match
    either the required type parameter type constraint, or if
    re-parameterizing, the new type constraints are a subtype of the parent.
    For example:

            subtype RangedInt,
                    as Parameterizable[Int, Range],
                    where {
                            my ($value, $range) = @_;
                            return ($value >= $range->{min} &&
                             $value =< $range->{max});
                    };

    Example subtype with additional constraints:

            subtype PositiveRangedInt,
                    as RangedInt,
                    where {
                            shift >= 0;                     
                    };

    Or you could have done the following instead:

            ## Subtype of Int for positive numbers
            subtype PositiveInt,
                    as Int,
                    where {
                            my ($value, $range) = @_;
                            return $value >= 0;
                    };

            ## subtype Range to re-parameterize Range with subtypes
            subtype PositiveRange,
                    as Range[max=>PositiveInt, min=>PositiveInt];
        
            ## create subtype via reparameterizing
            subtype PositiveRangedInt,
                    as RangedInt[PositiveRange];

    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 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.

  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 create a Parameterizable
    type like:

            subtype RequiredAgeInYears,
              as Int;

            subtype PersonOverAge,
              as Parameterizable[Person, RequiredAgeInYears]
              where {
                    my ($person, $required_years_old) = @_;
                    return $person->years_old > $required_years_old;
              }

    This would validate the following:

            my $person = Person->new(age=>35);
            PersonOverAge([18])->check($person);

    You can then apply the following coercion

            coerce PersonOverAge,
              from Dict[age=>int],
              via {Person->new(%$_)},
              from Int,
              via {Person->new(age=>$_)};

    This coercion would then apply to all the following:

            PersonOverAge([18])->check(30); ## via the Int coercion
            PersonOverAge([18])->check({age=>50}); ## via the Dict coercion

    However, you are not allowed to place coercions on parameterizable types
    that have had their constraining value filled, nor subtypes of such. For
    example:

            coerce PersonOverAge[18],
              from DateTime,
              via {$_->years};

    That would generate a hard exception. This is a limitation for now until
    I can devise a smarter way to cache the generated type constraints.
    However, I doubt it will be a significant limitation, since the general
    use case is supported.

    Lastly, the constraining value is available in the coercion in much the
    same way it is available to the constraint.

            ## Create a type constraint where a Person must be in the set
            subtype PersonInSet,
                    as Parameterizable[Person, PersonSet],
                    where {
                            my ($person, $person_set) = @_;
                            $person_set->find($person);
                    }

            coerce PersonInSet,
                    from HashRef,
                    via {
                            my ($hashref, $person_set) = @_;
                            return $person_set->create($hash_ref);
                    };

  Recursion
            TBD

TYPE CONSTRAINTS
    This type library defines the following constraints.

  Parameterizable[ParentTypeConstraint, ParameterizableValueTypeConstraint]
    Create a subtype of ParentTypeConstraint with a dependency on a value
    that can pass the ParameterizableValueTypeConstraint. If
    ParameterizableValueTypeConstraint is empty we default to the 'Any' type
    constraint (see Moose::Util::TypeConstraints).

    This creates a type constraint which must be further parameterized at
    later time before it can be used to ->check or ->validate a value.
    Attempting to do so will cause an exception.

AUTHOR
    John Napiorkowski, "<jjnapiork@cpan.org>"

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