From: John Napiorkowski Date: Mon, 28 Jun 2010 12:51:02 +0000 (-0400) Subject: docs changes all over X-Git-Tag: 0.05~5 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=9e662b6a5386d11f3eac5dc29abdc2746dd49001;p=gitmo%2FMooseX-Dependent.git docs changes all over --- diff --git a/Changes b/Changes index 1079cec..bc50241 100644 --- a/Changes +++ b/Changes @@ -1,5 +1,8 @@ Revision history for MooseX-Types-Parameterized +0.04 28 June 2010 + - More documentation fixes, no code changes + 0.03 25 June 2010 - more documentation fixes, better coecion docs - more tests diff --git a/lib/MooseX/Meta/TypeCoercion/Parameterizable.pm b/lib/MooseX/Meta/TypeCoercion/Parameterizable.pm index 6960092..780567f 100644 --- a/lib/MooseX/Meta/TypeCoercion/Parameterizable.pm +++ b/lib/MooseX/Meta/TypeCoercion/Parameterizable.pm @@ -10,9 +10,9 @@ MooseX::Meta::TypeCoercion::Parameterizable - Coerce Parameterizable type constr =head1 DESCRIPTION -This class is not intended for public consumption. Please don't subclass it -or rely on it. Chances are high stuff here is going to change a lot. - +Coercion Meta Class, intended to make sure coercions work correctly with +parameterized types. You probably won't consume or subclass this class directly + =head1 METHODS This class defines the following methods. @@ -20,10 +20,10 @@ This class defines the following methods. =head add_type_coercions method modification to throw exception should we try to add a coercion on a -parameterizable type that is already defined by a constraining value. We do this -since defined parameterizable type constraints inherit their coercion from the parent -constraint. It makes no sense to even be using parameterizable types if you know the -constraining value beforehand! +parameterizable type that is already defined by a constraining value. We do +this since defined parameterizable type constraints inherit their coercion from +the parent constraint. It makes no sense to even be using parameterizable +types if you know the constraining value beforehand! =cut @@ -38,12 +38,13 @@ around 'add_type_coercions' => sub { ## These two are here until I can merge change upstream to Moose. These are two -## very minor changes we can probably just put into Moose without breaking stuff +## very minor changes we can probably just put into Moose without breaking stuff. +## Hopefully can can eventually stop doing this. sub coerce { my $self = shift @_; my $coderef = $self->_compiled_type_coercion; - return $coderef->(@_); + return $coderef->(@_); ## <== in Moose we don't call on @_, but $_[1] } sub compile_type_coercion { @@ -73,7 +74,7 @@ sub compile_type_coercion { my ($constraint, $converter) = @$coercion; if ($constraint->($thing)) { local $_ = $thing; - return $converter->($thing, @_); + return $converter->($thing, @_); ## <== Here also we pass @_ which Moose doesn't } } return $thing; diff --git a/lib/MooseX/Meta/TypeConstraint/Parameterizable.pm b/lib/MooseX/Meta/TypeConstraint/Parameterizable.pm index 5e3e43d..5163922 100644 --- a/lib/MooseX/Meta/TypeConstraint/Parameterizable.pm +++ b/lib/MooseX/Meta/TypeConstraint/Parameterizable.pm @@ -12,18 +12,15 @@ extends 'Moose::Meta::TypeConstraint'; =head1 NAME -MooseX::Meta::TypeConstraint::Parameterizable - Metaclass for Parameterizable type constraints. +MooseX::Meta::TypeConstraint::Parameterizable - Parameterizable Meta Class. =head1 DESCRIPTION -see L for how to use parameterizable +See L for how to use parameterizable types. This class is a subclass of L which provides the gut functionality to enable parameterizable type constraints. -This class is not intended for public consumption. Please don't subclass it -or rely on it. Chances are high stuff here is going to change a lot. For -example, I will probably refactor this into several classes to get rid of all -the ugly conditionals. +You probably won't need to subclass or consume this class directly. =head1 ATTRIBUTES @@ -37,7 +34,7 @@ The type constraint whose validity is being made parameterizable. has 'parent_type_constraint' => ( is=>'ro', - isa=>'Object', + isa=>Moose::Util::TypeConstraints::class_type('Moose::Meta::TypeConstraint'), default=> sub { Moose::Util::TypeConstraints::find_type_constraint("Any"); }, @@ -54,7 +51,7 @@ constraining value of the parameterizable type. has 'constraining_value_type_constraint' => ( is=>'ro', - isa=>'Object', + isa=>Moose::Util::TypeConstraints::class_type('Moose::Meta::TypeConstraint'), default=> sub { Moose::Util::TypeConstraints::find_type_constraint("Any"); }, @@ -67,6 +64,9 @@ This is the actual value that constraints the L =cut +## TODO, this is where we probably should break out Parameterized stuff from +## parameterizable... + has 'constraining_value' => ( is=>'ro', predicate=>'has_constraining_value', @@ -78,12 +78,9 @@ This class defines the following methods. =head2 new -Do some post build stuff +Do some post build stuff, mostly make sure we set the correct coercion object. =cut - -## Right now I add in the parameterizable type coercion until I can merge some Moose -## changes upstream. around 'new' => sub { my ($new, $class, @args) = @_; @@ -188,7 +185,7 @@ sub parameterize { if(my $exists = Moose::Util::TypeConstraints::find_type_constraint($name)) { return $exists; } else { - my $type_constraint = $class->new( + return $class->new( name => $name, parent => $self, constraint => $self->constraint, @@ -197,10 +194,6 @@ sub parameterize { constraining_value_type_constraint => $self->constraining_value_type_constraint, message => $self->message, ); - - ## TODO This is probably going to have to go away (too many things added to the registry) - ##Moose::Util::TypeConstraints::get_type_constraint_registry->add_type_constraint($type_constraint); - return $type_constraint; } } } @@ -321,19 +314,6 @@ modify this method so that we pass along the constraining value to the constrain coderef and also throw the correct error message if the constraining value does not match it's requirement. -around 'compile_type_constraint' => sub { - my ($compile_type_constraint, $self, @args) = @_; - - if($self->has_type_constraints) { - my $type_constraints = $self->type_constraints; - my $constraint = $self->generate_constraint_for($type_constraints); - $self->_set_constraint($constraint); - } - - return $self->$compile_type_constraint(@args); -}; - - =cut around '_compiled_type_constraint' => sub { diff --git a/lib/MooseX/Types/Parameterizable.pm b/lib/MooseX/Types/Parameterizable.pm index 9267ab2..48ac2db 100644 --- a/lib/MooseX/Types/Parameterizable.pm +++ b/lib/MooseX/Types/Parameterizable.pm @@ -2,7 +2,7 @@ package MooseX::Types::Parameterizable; use 5.008; -our $VERSION = '0.03'; +our $VERSION = '0.04'; $VERSION = eval $VERSION; use Moose::Util::TypeConstraints; @@ -75,7 +75,7 @@ A L library for creating parameterizable types. A parameterizabl 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. +coercions you define for a given type constraint. If you have L experience, you probably are familiar with the builtin parameterizable type constraints 'ArrayRef' and 'HashRef'. This type constraint @@ -104,15 +104,25 @@ values for an Int (integer) type constraint: RangedInt([{min=>10,max=>100}])->check(50); ## OK RangedInt([{min=>50, max=>75}])->check(99); ## Not OK, exceeds max -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 or L.) +This is useful since it lets you generate common patterns of type constraints +rather than build a custom type constraint for all similar cases. + +The type parameter must be valid against the 'constrainting' type constraint used +in the Parameterizable condition. 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 or L.) + 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! -If you can't accept a hard exception here, you'll need to test the constraining -values first, as in: +In the above case the 'min' value is larger than the 'max', which violates the +Range constraint. We throw a hard error here since I think incorrect type +parameters are most likely to be the result of a typo or other true error +conditions. + +If you can't accept a hard exception here, you can either trap it as advised +above or you need to test the constraining values first, as in: my $range = {min=>99, max=>10}; if(my $err = Range->validate($range)) { @@ -130,8 +140,7 @@ parameters, so that the above could also be written as: RangedInt([min=>99, max=>10])->check(10); ## Exception, not 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. +conciseness of your type constraint declarations. Also note that if you 'chain' parameterization results with a method call like: @@ -164,8 +173,8 @@ Example subtype with additional constraints: shift >= 0; }; -In this case you'd now have a parameterizable type constraint called which -would work like: +In this case you'd now have a parameterizable type constraint which would +work like: Test::More::ok PositiveRangedInt([{min=>-10, max=>75}])->check(5); Test::More::ok !PositiveRangedInt([{min=>-10, max=>75}])->check(-5); @@ -209,7 +218,8 @@ 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. +could stick it wherever you'd need an Int. You can't change the parent, even +to make it a subclass of Int. =head2 Coercions @@ -217,7 +227,7 @@ A type coerction is a rule that allows you to transform one type from one or more other types. Please see L for an example of type coercions if you are not familiar with the subject. -L support type coercions in all the ways you +L supports type coercions in all the ways you would expect. In addition, it also supports a limited form of type coercion inheritance. Generally speaking, type constraints don't inherit coercions since this would rapidly become confusing. However, since your parameterizable type @@ -226,7 +236,8 @@ from a 'base' parameterizable type constraint to its 'child' parameterized sub types. For the purposes of this discussion, a parameterizable type is a subtype created -when you say, "as Parameterizable[..." in your sub type declaration. For example +when you say, "as Parameterizable[..." in your sub type declaration. For +example: subtype Varchar, as Parameterizable[Str, Int], @@ -252,7 +263,7 @@ parameter. We can apply some coercions to it: This parameterizable subtype, "Varchar" itself is something you'd never use directly to constraint a value. In other words you'd never do something like: - has name => (isa=>Varchar, ...) + has name => (isa=>Varchar, ...); ## Why not just use a Str? You are going to do this: @@ -298,15 +309,13 @@ how most L authors expect type constraints to work. This type library defines the following constraints. -=head2 Parameterizable[ParentTypeConstraint, ParameterizableValueTypeConstraint] +=head2 Parameterizable[ParentTypeConstraint, ConstrainingValueTypeConstraint] Create a subtype of ParentTypeConstraint with a dependency on a value that can -pass the ParameterizableValueTypeConstraint. If ParameterizableValueTypeConstraint is empty +pass the ConstrainingValueTypeConstraint. If ConstrainingValueTypeConstraint is empty we default to the 'Any' type constraint (see L). - -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. +This is useful if you are creating some base Parameterizable type constraints +that you intend to sub class. =cut @@ -318,6 +327,12 @@ Moose::Util::TypeConstraints::get_type_constraint_registry->add_type_constraint( ) ); +=head1 SEE ALSO + +The following modules or resources may be of interest. + +L, L, L + =head1 AUTHOR John Napiorkowski, C<< >>