Improve documentation on Moose::Util::TypConstraints "role_type" and "class_type"

[gitmo/Moose.git] / lib / Moose / Util / TypeConstraints.pm

diff --git a/lib/Moose/Util/TypeConstraints.pm b/lib/Moose/Util/TypeConstraints.pm
index 9344607..92652b9 100644 (file)
--- a/lib/Moose/Util/TypeConstraints.pm
+++ b/lib/Moose/Util/TypeConstraints.pm
@@ -69,13 +69,26 @@ sub export_type_constraints_as_functions {
 }
 
 sub create_type_constraint_union {
+    _create_type_constraint_union(\@_);
+}
+
+sub create_named_type_constraint_union {
+    my $name = shift;
+    _create_type_constraint_union($name, \@_);
+}
+
+sub _create_type_constraint_union {
+    my $name;
+    $name = shift if @_ > 1;
+    my @tcs = @{ shift() };
+
     my @type_constraint_names;
 
-    if ( scalar @_ == 1 && _detect_type_constraint_union( $_[0] ) ) {
-        @type_constraint_names = _parse_type_constraint_union( $_[0] );
+    if ( scalar @tcs == 1 && _detect_type_constraint_union( $tcs[0] ) ) {
+        @type_constraint_names = _parse_type_constraint_union( $tcs[0] );
     }
     else {
-        @type_constraint_names = @_;
+        @type_constraint_names = @tcs;
     }
 
     ( scalar @type_constraint_names >= 2 )
@@ -88,10 +101,15 @@ sub create_type_constraint_union {
             "Could not locate type constraint ($_) for the union");
     } @type_constraint_names;
 
-    return Moose::Meta::TypeConstraint::Union->new(
-        type_constraints => \@type_constraints );
+    my %options = (
+      type_constraints => \@type_constraints
+    );
+    $options{name} = $name if defined $name;
+
+    return Moose::Meta::TypeConstraint::Union->new(%options);
 }
 
+
 sub create_parameterized_type_constraint {
     my $type_constraint_name = shift;
     my ( $base_type, $type_parameter )
@@ -412,12 +430,12 @@ sub union {
   if ( @constraints == 1 && ref $constraints[0] eq 'ARRAY' ) {
     @constraints = @{ $constraints[0] };
   }
-  my $tc = create_type_constraint_union( @constraints );
   if ( defined $type_name ) {
-    $tc->name( $type_name );
-    return register_type_constraint( $tc );
+    return register_type_constraint(
+      create_named_type_constraint_union( $type_name, @constraints )
+    );
   }
-  return $tc;
+  return create_type_constraint_union( @constraints );
 }
 
 sub create_enum_type_constraint {
@@ -732,8 +750,14 @@ __END__
       from 'Str',
       via { 0+$_ };
 
+  class_type 'DateTimeish', { class => 'DateTime' };
+
+  role_type 'Barks', { role => 'Some::Library::Role::Barks' };
+
   enum 'RGBColors', [qw(red green blue)];
 
+  union 'StringOrArray', [qw( String Array )];
+
   no Moose::Util::TypeConstraints;
 
 =head1 DESCRIPTION
@@ -939,11 +963,31 @@ just a hashref of parameters:
 Creates a new subtype of C<Object> with the name C<$class> and the
 metaclass L<Moose::Meta::TypeConstraint::Class>.
 
+  # Create a type called 'Box' which tests for objects which ->isa('Box')
+  class_type 'Box';
+
+Additionally, you can create a class_type which is a shorthand for another class.
+
+  # Create a type called 'Box' which tests for objects which ->isa('ObjectLibrary::Box');
+  class_type 'Box', { class => 'ObjectLibrary::Box' };
+
+But it's only really necessary to do this if you're working with L<MooseX::Types>.
+
 =item B<role_type ($role, ?$options)>
 
 Creates a C<Role> type constraint with the name C<$role> and the
 metaclass L<Moose::Meta::TypeConstraint::Role>.
 
+  # Create a type called 'Walks' which tests for objects which ->does('Walks')
+  role_type 'Walks';
+
+Additionally, you can create a role_type which is a shorthand for another role.
+
+  # Create a type called 'Walks' which tests for objects which ->does('MooseX::Role::Walks');
+  role_type 'Walks', { role => 'MooseX::Role::Walks' };
+
+But it's only really necessary to do this if you're working with L<MooseX::Types>.
+
 =item B<maybe_type ($type)>
 
 Creates a type constraint for either C<undef> or something of the
@@ -990,6 +1034,33 @@ can then be used in an attribute definition like so:
       isa => enum([qw[ ascending descending ]]),
   );
 
+=item B<union ($name, \@constraints)>
+
+This will create a basic subtype where any of the provided constraints
+may match in order to satisfy this constraint.
+
+=item B<union (\@constraints)>
+
+If passed an ARRAY reference as the only parameter instead of the
+C<$name>, C<\@constraints> pair, this will create an unnamed union.
+This can then be used in an attribute definition like so:
+
+  has 'items' => (
+      is => 'ro',
+      isa => union([qw[ Str ArrayRef ]]),
+  );
+
+This is similar to the existing string union:
+
+  isa => 'Str|ArrayRef'
+
+except that it supports anonymous elements as child constraints:
+
+  has 'color' => (
+    isa => 'ro',
+    isa => union([ 'Int',  enum([qw[ red green blue ]]) ]),
+  );
+
 =item B<as 'Parent'>
 
 This is just sugar for the type constraint construction syntax.
@@ -1210,6 +1281,8 @@ form. This removes any whitespace in the string.
 
 =item B<create_type_constraint_union($pipe_separated_types | @type_constraint_names)>
 
+=item B<create_named_type_constraint_union($name, $pipe_separated_types | @type_constraint_names)>
+
 This can take a union type specification like C<'Int|ArrayRef[Int]'>,
 or a list of names. It returns a new
 L<Moose::Meta::TypeConstraint::Union> object.