fix documentation of type heirarchy

[gitmo/Moose.git] / lib / Moose / Manual / Types.pod

diff --git a/lib/Moose/Manual/Types.pod b/lib/Moose/Manual/Types.pod
index 6a18b72..1b54e65 100644 (file)
--- a/lib/Moose/Manual/Types.pod
+++ b/lib/Moose/Manual/Types.pod
@@ -34,26 +34,26 @@ data, and it also contributes greatly to code maintainability.
 The basic Moose type hierarchy looks like this
 
   Any
-  Item
-      Bool
-      Maybe[`a]
-      Undef
-      Defined
-          Value
-              Str
-                  Num
-                      Int
-                  ClassName
-                  RoleName
-          Ref
-              ScalarRef[`a]
-              ArrayRef[`a]
-              HashRef[`a]
-              CodeRef
-              RegexpRef
-              GlobRef
+      Item
+          Bool
+          Maybe[`a]
+          Undef
+          Defined
+              Value
+                  Str
+                      Num
+                          Int
+                      ClassName
+                      RoleName
+              Ref
+                  ScalarRef[`a]
+                  ArrayRef[`a]
+                  HashRef[`a]
+                  CodeRef
+                  RegexpRef
+                  GlobRef
                   FileHandle
-              Object
+                  Object
 
 In practice, the only difference between C<Any> and C<Item> is
 conceptual. C<Item> is used as the top-level type in the hierarchy.
@@ -166,14 +166,16 @@ A subtype can also define its own constraint failure message. This
 lets you do things like have an error "The value you provided (20),
 was not a valid rating, which must be a number from 1-10." This is
 much friendlier than the default error, which just says that the value
-failed a validation check for the type.
+failed a validation check for the type. The default error can, however,
+be made more friendly by installing L<Devel::PartialDump> (version 0.14 or
+higher), which Moose will use if possible to display the invalid value.
 
 Here's a simple (and useful) subtype example:
 
-  subtype 'PositiveInt'
-      => as 'Int'
-      => where { $_ > 0 }
-      => message { "The number you provided, $_, was not a positive number" }
+  subtype 'PositiveInt',
+      as 'Int',
+      where { $_ > 0 },
+      message { "The number you provided, $_, was not a positive number" };
 
 Note that the sugar functions for working with types are all exported
 by L<Moose::Util::TypeConstraints>.
@@ -202,7 +204,7 @@ export your types as perl constants.
   has 'counter' => (is => 'rw', isa => PositiveInt);
 
 This lets you use a short name rather than needing to fully qualify the name
-everywhere. It also allows you to write easily create parameterized types:
+everywhere. It also allows you to easily create parameterized types:
 
   has 'counts' => (is => 'ro', isa => HashRef[PositiveInt]);
 
@@ -213,12 +215,12 @@ robust than the string type parsing for complex cases.
 
 A coercion lets you tell Moose to automatically convert one type to another.
 
-  subtype 'ArrayRefOfInts'
-      => as 'ArrayRef[Int]';
+  subtype 'ArrayRefOfInts',
+      as 'ArrayRef[Int]';
 
-  coerce 'ArrayRefOfInts'
-      => from 'Int'
-      => via { [ $_ ] };
+  coerce 'ArrayRefOfInts',
+      from 'Int',
+      via { [ $_ ] };
 
 You'll note that we created a subtype rather than coercing C<ArrayRef[Int]>
 directly. It's a bad idea to add coercions to the raw built in
@@ -249,13 +251,13 @@ object will have C<[ 42 ]> as its C<sizes> attribute.
 Deep coercion is the coercion of type parameters for parameterized
 types. Let's take these types as an example:
 
-  subtype 'HexNum'
-      => as 'Str'
-      => where { /[a-f0-9]/i };
+  subtype 'HexNum',
+      as 'Str',
+      where { /[a-f0-9]/i };
 
-  coerce 'Int'
-      => from 'HexNum'
-      => via { hex $_ };
+  coerce 'Int',
+      from 'HexNum',
+      via { hex $_ };
 
   has 'sizes' => (
       is     => 'ro',
@@ -269,15 +271,15 @@ attribute, Moose will not do any coercion.
 However, you can define a set of subtypes to enable coercion between
 two parameterized types.
 
-  subtype 'ArrayRefOfHexNums'
-      => as 'ArrayRef[HexNum]';
+  subtype 'ArrayRefOfHexNums',
+      as 'ArrayRef[HexNum]';
 
-  subtype 'ArrayRefOfInts'
-      => as 'ArrayRef[Int]';
+  subtype 'ArrayRefOfInts',
+      as 'ArrayRef[Int]';
 
-  coerce 'ArrayRefOfInts'
-      => from 'ArrayRefOfHexNums'
-      => via { [ map { hex } @{$_} ] };
+  coerce 'ArrayRefOfInts',
+      from 'ArrayRefOfHexNums',
+      via { [ map { hex } @{$_} ] };
 
   Foo->new( sizes => [ 'a1', 'ff', '22' ] );
 
@@ -287,9 +289,9 @@ Moose does not attempt to chain coercions, so it will not
 coerce a single hex number. To do that, we need to define a separate
 coercion:
 
-  coerce 'ArrayRefOfInts'
-      => from 'HexNum'
-      => via { [ hex $_ ] };
+  coerce 'ArrayRefOfInts',
+      from 'HexNum',
+      via { [ hex $_ ] };
 
 Yes, this can all get verbose, but coercion is tricky magic, and we
 think it's best to make it explicit.
@@ -316,9 +318,7 @@ coercion might be a better answer.
 For our example above, we might want to be more specific, and insist
 that output be an object with a C<print> method:
 
-  subtype 'CanPrint'
-      => as 'Object'
-      => where { $_->can('print') };
+  duck_type 'CanPrint', [qw(print)];
 
 We can coerce file handles to an object that satisfies this condition
 with a simple wrapper class:
@@ -358,13 +358,13 @@ make your class internals simpler.
 
 The L<Moose::Util::TypeConstraints> module exports a number of helper
 functions for creating specific kinds of types. These include
-C<class_type>, C<role_type>, and C<maybe_type>. See the docs for
-details.
+C<class_type>, C<role_type>, C<maybe_type>, and C<duck_type>. See the
+docs for details.
 
 One helper worth noting is C<enum>, which allows you to create a
 subtype of C<Str> that only allows the specified values:
 
-  enum 'RGB' => qw( red green blue );
+  enum 'RGB', [qw( red green blue )];
 
 This creates a type named C<RGB>.