From: Cory Watson <github@onemogin.com>
Date: Tue, 1 Dec 2009 23:16:44 +0000 (-0600)
Subject: POD
X-Git-Tag: 0.05~9
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=1925805868ca4720ef9865a976f05a202ed2f865;p=gitmo%2FMooseX-UndefTolerant.git

POD
---

diff --git a/lib/MooseX/UndefTolerant.pm b/lib/MooseX/UndefTolerant.pm
index e8662fd..c437b92 100644
--- a/lib/MooseX/UndefTolerant.pm
+++ b/lib/MooseX/UndefTolerant.pm
@@ -17,12 +17,81 @@ __END__
 
 =head1 NAME
 
-MooseX::Attribute::UndefTolerant - The great new MooseX::Attribute::UndefTolerant!
+MooseX::UndefTolerant - Make your attribute(s) tolerant to undef intitialization
 
 =head1 SYNOPSIS
 
-    use MooseX::Attribute::UndefTolerant;
+  package My::Class;
 
+  use Moose;
+  use MooseX::UndefTolerant;
+
+  has 'name' => (
+    is => 'ro',
+    isa => 'Str',
+    predicate => 'has_name'
+  );
+
+  # Meanwhile, under the city...
+
+  # Doesn't explode
+  my $class = My::Class->new(name => undef);
+  $class->has_name # False!
+
+Or, if you only want one attribute to have this behaviour:
+
+  package My:Class;
+  use Moose;
+
+  use MooseX::UndefTolerant::Attribute;
+
+  has 'bar' => (
+      traits => [ qw(MooseX::UndefTolerant::Attribute)],
+      is => 'ro',
+      isa => 'Num',
+      predicate => 'has_bar'
+  );
+
+=head1 DESCRIPTION
+
+Loading this module in your L<Moose> class makes initialization of your
+attributes tolerant of undef.  If you specify the value of undef to any of
+the attributes they will not be initialized.  Effectively behaving as if you
+had not provided a value at all.
+
+=head1 MOTIVATION
+
+I often found myself in this quandry:
+
+  package My:Class;
+  use Moose;
+
+  has 'foo' => (
+    is => 'ro',
+    isa => 'Str',
+  );
+
+  # ... then
+
+  my $foo = ... # get the param from something
+
+  my $class = My:Class->new(foo => $foo, bar => 123);
+
+What if foo is undefined?  I didn't want to change my attribute to be
+Maybe[Str] and I still want my predicate (C<has_foo>) to work.  The only
+real solution was:
+
+  if(defined($foo)) {
+    $class = My:CLass->new(foo => $foo, bar => 123);
+  } else {
+    $class = My:CLass->new(bar => 123);
+  }
+
+Or some type of codemulch using ternarys.  This module allows you to make
+your attributes more tolerant of undef so that you can keep the first
+example: have your cake and eat it too!
+
+=head1 PER ATTRIBUTE
 
 =head1 AUTHOR
 
@@ -30,6 +99,8 @@ Cory G Watson, C<< <gphat at cpan.org> >>
 
 =head1 ACKNOWLEDGEMENTS
 
+Many thanks to the crew in #moose who talked me through this module:
+
 Hans Dieter Pearcey (confound)
 
 Jesse Luehrs (doy)
@@ -52,5 +123,4 @@ by the Free Software Foundation; or the Artistic License.
 
 See http://dev.perl.org/licenses/ for more information.
 
-
 =cut
diff --git a/lib/MooseX/UndefTolerant/Attribute.pm b/lib/MooseX/UndefTolerant/Attribute.pm
index e1aee78..1c99219 100644
--- a/lib/MooseX/UndefTolerant/Attribute.pm
+++ b/lib/MooseX/UndefTolerant/Attribute.pm
@@ -12,4 +12,51 @@ around('initialize_instance_slot', sub{
     $self->$orig(@_)
 });
 
-1;
\ No newline at end of file
+1;
+
+=head1 NAME
+
+MooseX::UndefTolerant::Attribute - Make your attribute tolerant to undef intitialization
+
+=head1 SYNOPSIS
+
+  package My:Class;
+  use Moose;
+
+  use MooseX::UndefTolerant::Attribute;
+
+  has 'bar' => (
+      traits => [ qw(MooseX::UndefTolerant::Attribute)],
+      is => 'ro',
+      isa => 'Num',
+      predicate => 'has_bar'
+  );
+
+  # Meanwhile, under the city...
+
+  # Doesn't explode
+  my $class = My::Class->new(bar => undef);
+  $class->has_bar # False!
+
+=head1 DESCRIPTION
+
+Applying this trait to your attribute makes it's initialization tolerant of
+of undef.  If you specify the value of undef to any of the attributes they
+will not be initialized.  Effectively behaving as if you had not provided a
+value at all.
+
+=head1 AUTHOR
+
+Cory G Watson, C<< <gphat at cpan.org> >>
+
+=head1 COPYRIGHT & LICENSE
+
+Copyright 2009 Cory G Watson.
+
+This program is free software; you can redistribute it and/or modify it
+under the terms of either: the GNU General Public License as published
+by the Free Software Foundation; or the Artistic License.
+
+See http://dev.perl.org/licenses/ for more information.
+
+=cut