From: Jess Robinson <cpan@desert-island.me.uk>
Date: Wed, 5 Sep 2007 22:25:34 +0000 (+0000)
Subject: Add various docs about checking types of attributes against constraints
X-Git-Tag: 0_26~27
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=bcbaa8457d0c6ee7fcd5fc12c0fa9ad7d66a2aa6;p=gitmo%2FMoose.git

Add various docs about checking types of attributes against constraints
---

diff --git a/lib/Moose/Cookbook/Recipe1.pod b/lib/Moose/Cookbook/Recipe1.pod
index f9382d5..ffbe46f 100644
--- a/lib/Moose/Cookbook/Recipe1.pod
+++ b/lib/Moose/Cookbook/Recipe1.pod
@@ -10,8 +10,14 @@ Moose::Cookbook::Recipe1 - The (always classic) B<Point> example.
   package Point;
   use Moose;
   	
-  has 'x' => (isa => 'Int', is => 'ro');
-  has 'y' => (isa => 'Int', is => 'rw');
+  has 'x' => (isa => 'Int', is => 'ro', clearer => 'clear_x' );
+  has 'y' => (isa => 'Int', is => 'rw', clearer => 'clear_y');
+  
+  sub clear {
+      my $self = shift;
+      $self->clear_x();
+      $self->clear_y();    # or $self->y(0);
+  }
   
   sub clear {
       my $self = shift;
diff --git a/lib/Moose/Cookbook/Snack/Types.pod b/lib/Moose/Cookbook/Snack/Types.pod
new file mode 100644
index 0000000..5bc9e51
--- /dev/null
+++ b/lib/Moose/Cookbook/Snack/Types.pod
@@ -0,0 +1,75 @@
+
+=pod
+
+=head1 NAME
+
+Moose::Cookbook::Snack::Types - Snippets of code for using Types and Type Constraints
+
+=head1 SYNOPSIS
+
+  package Point;
+  use Moose;
+  	
+  has 'x' => (isa => 'Int', is => 'ro' );
+  has 'y' => (isa => 'Int', is => 'rw' );
+  
+  package main;
+
+  my $point = eval {
+    Point->new(x => 'fifty', y => 'fourty');
+  };
+
+  if($@) {
+    print "Oops: $@";
+  }
+
+  my $point;
+  my $xval = 'fourty-two';
+  my $xattribute = Point->meta->find_attribute_by_name('x');
+  my $xtype_constraint = $xattribute->type_constraint;
+  if($xtype_constraint->check($xval)) {
+    $point = Point->new(x => $xval, y => 0);
+  } else {
+    print "Value: $xval is not an " . $xtype_constraint->name . "\n";
+  }
+
+
+=head1 DESCRIPTION
+
+This is the Point example from (L<Moose::Cookbook::Recipe1>) with added
+type checking. 
+
+If we try to assign a string value to an attribute that is defined as
+being of type Int, Moose will die with an explicit error message
+saying which attribute failed which type constaint with which
+value. The eval example catches this message and displays it.
+
+The second example fetches the type constraint instance and asks it to
+check the value we are about to set, before we try and set it.
+
+=head1 SEE ALSO
+
+=over 4
+
+=item L<Moose::Cookbook::Recipe1>
+
+=item L<Moose::Utils::TypeConstraints>
+
+=item L<Moose::Meta::Attribute>
+
+=back
+
+=head1 AUTHOR
+
+Jess Robinson <cpan@desert-island.me.uk>
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 2006, 2007 by Infinity Interactive, Inc.
+
+L<http://www.iinteractive.com>
+
+This library is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself.
+
+=cut
\ No newline at end of file
diff --git a/lib/Moose/Cookbook/WTF.pod b/lib/Moose/Cookbook/WTF.pod
index 57a56f9..15967d9 100644
--- a/lib/Moose/Cookbook/WTF.pod
+++ b/lib/Moose/Cookbook/WTF.pod
@@ -111,7 +111,7 @@ Here is some sample code:
 
 =head2 Moose and Attributes
 
-=head3 Why doesn't attributes I inherited from a superclass work?
+=head3 Why don't attributes I inherited from a superclass work?
 
 Currently when you subclass a module, this is done at runtime with
 the C<extends> keyword but attributes are checked at compile time
diff --git a/lib/Moose/Meta/Attribute.pm b/lib/Moose/Meta/Attribute.pm
index e50fe7d..f3d8967 100644
--- a/lib/Moose/Meta/Attribute.pm
+++ b/lib/Moose/Meta/Attribute.pm
@@ -518,6 +518,25 @@ will behave just as L<Class::MOP::Attribute> does.
 
 =item B<set_value>
 
+  eval { $point->meta->get_attribute('x')->set_value($point, 'fourty-two') };
+  if($@) {
+    print "Oops: $@\n";
+  }
+
+I<Attribute (x) does not pass the type constraint (Int) with 'fourty-two'>
+
+Before setting the value, a check is made on the type constraint of
+the attribute, if it has one, to see if the value passes it. If the
+value fails to pass, the set operation dies with a L<Carp/confess>.
+
+Any coercion to convert values is done before checking the type constraint.
+
+To check a value against a type constraint before setting it, fetch the
+attribute instance using L<Moose::Meta::Attribute/find_attribute_by_name>,
+fetch the type_constraint from the attribute using L<Moose::Meta::Attribute/type_constraint>
+and call L<Moose::Meta::TypeConstraint/check>. See L<Moose::Cookbook::RecipeX>
+for an example.
+
 =back
 
 =head2 Additional Moose features