bumped minimum version to fix problem with overloading on certain Perls. this was...

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

diff --git a/lib/MooseX/Types.pm b/lib/MooseX/Types.pm
index f2c60a7..eabd450 100644 (file)
--- a/lib/MooseX/Types.pm
+++ b/lib/MooseX/Types.pm
@@ -19,8 +19,7 @@ use Carp::Clan                      qw( ^MooseX::Types );
 
 use namespace::clean -except => [qw( meta )];
 
-our $VERSION = 0.06;
-
+our $VERSION = 0.07;
 my $UndefMsg = q{Action for type '%s' not yet defined in library '%s'};
 
 =head1 SYNOPSIS
@@ -40,7 +39,7 @@ my $UndefMsg = q{Action for type '%s' not yet defined in library '%s'};
   # import builtin types
   use MooseX::Types::Moose 'Int';
 
-  # type definition
+  # type definition.
   subtype PositiveInt, 
       as Int, 
       where { $_ > 0 },
@@ -280,7 +279,7 @@ types you define in a type library.
     has 'attr' => (isa=>HashRef|Int);
 
 And everything should just work as you'd think.
-    
+
 =head1 METHODS
 
 =head2 import
@@ -339,9 +338,16 @@ yet defined.
 
 sub type_export_generator {
     my ($class, $type, $name) = @_;
+    
+    ## Return an anonymous subroutine that will generate the proxied type
+    ## constraint for you.
+    
     return sub {
         my $type_constraint;
         if(defined(my $params = shift @_)) {
+            ## We currently only allow a TC to accept a single, ArrayRef
+            ## parameter, as in HashRef[Int], where [Int] is what's inside the
+            ## ArrayRef passed.
             if(ref $params eq 'ARRAY') {
                 $type_constraint = $class->create_arged_type_constraint($name, @$params);
             } else {
@@ -355,6 +361,10 @@ sub type_export_generator {
          
         my $type_decorator = $class->create_type_decorator($type_constraint);
         
+        ## If there are additional args, that means it's probably stuff that
+        ## needs to be returned to the subtype.  Not an ideal solution here but
+        ## doesn't seem to cause trouble.
+        
         if(@_) {
             return ($type_decorator, @_);
         } else {
@@ -365,14 +375,15 @@ sub type_export_generator {
 
 =head2 create_arged_type_constraint ($name, @args)
 
-Given a String $name with @args find the matching typeconstraint.
+Given a String $name with @args find the matching typeconstraint and parameterize
+it with @args.
 
 =cut
 
 sub create_arged_type_constraint {
-    my ($class, $name, @args) = @_;
-    my $type_constraint = Moose::Util::TypeConstraints::find_or_create_type_constraint($name);
-       return $type_constraint->parameterize(@args)
+    my ($class, $name, @args) = @_;  
+    my $type_constraint = Moose::Util::TypeConstraints::find_or_create_type_constraint("$name");
+       return $type_constraint->parameterize(@args);
 }
 
 =head2 create_base_type_constraint ($name)
@@ -440,11 +451,36 @@ sub check_export_generator {
 
 =head1 CAVEATS
 
+The following are lists of gotcha's and their workarounds for developers coming
+from the standard string based type constraint names
+
+=head2 Uniqueness
+
 A library makes the types quasi-unique by prefixing their names with (by
 default) the library package name. If you're only using the type handler
 functions provided by MooseX::Types, you shouldn't ever have to use
 a type's actual full name.
 
+=head2 Argument separation ('=>' versus ',')
+
+The Perlop manpage has this to say about the '=>' operator: "The => operator is
+a synonym for the comma, but forces any word (consisting entirely of word
+characters) to its left to be interpreted as a string (as of 5.001). This
+includes words that might otherwise be considered a constant or function call."
+
+Due to this stringification, the following will NOT work as you might think:
+
+  subtype StrOrArrayRef => as Str|ArrayRef;
+  
+The 'StrOrArrayRef' will have it's stringification activated this causes the
+subtype to not be created.  Since the bareword type constraints are not strings
+you really should not try to treat them that way.  You will have to use the ','
+operator instead.  The author's of this package realize that all the L<Moose>
+documention and examples nearly uniformly use the '=>' version of the comma
+operator and this could be an issue if you are converting code.
+
+Patches welcome for discussion.
+    
 =head1 SEE ALSO
 
 L<Moose>,