removed some bad examples

[gitmo/MooseX-Dependent.git] / lib / MooseX / Types / Parameterizable.pm

diff --git a/lib/MooseX/Types/Parameterizable.pm b/lib/MooseX/Types/Parameterizable.pm
index d62d7fe..6956980 100644 (file)
--- a/lib/MooseX/Types/Parameterizable.pm
+++ b/lib/MooseX/Types/Parameterizable.pm
@@ -36,6 +36,8 @@ The follow is example usage.
       },
       message { "'$_' is too long"  };
 
+    ## Coerce an ArrayRef to a string via concatenation.
+
     coerce Varchar,
       from ArrayRef,
       via { 
@@ -130,14 +132,14 @@ 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:
+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
 
@@ -161,7 +163,18 @@ Example subtype with additional 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,
@@ -179,35 +192,29 @@ Or you could have done the following instead:
     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,