X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=gitmo%2FMooseX-UndefTolerant.git;a=blobdiff_plain;f=README;h=c88c928551a3e036ac02eaa36e3146489e733160;hp=58d1fbfb987ce4e09f9178567efcf42165871bac;hb=bd7aab04aceda77a0bef5ac5a42ec052e63a1648;hpb=670193cb8c23f17567103bb514c2080f9538f345

diff --git a/README b/README
index 58d1fbf..c88c928 100644
--- a/README
+++ b/README
@@ -1,55 +1,107 @@
-MooseX-UndefTolerant
+NAME
+    MooseX::UndefTolerant - Make your attribute(s) tolerant to undef
+    initialization
 
-The README is used to introduce the module and provide instructions on
-how to install the module, any machine dependencies it may have (for
-example C compilers and installed libraries) and any other information
-that should be provided before the module is installed.
+SYNOPSIS
+      package My::Class;
 
-A README file is required for CPAN modules since CPAN extracts the README
-file from a module distribution so that people browsing the archive
-can use it to get an idea of the module's uses. It is usually a good idea
-to provide version information here so that people can decide whether
-fixes for the module are worth downloading.
+      use Moose;
+      use MooseX::UndefTolerant;
 
+      has 'name' => (
+        is => 'ro',
+        isa => 'Str',
+        predicate => 'has_name'
+      );
 
-INSTALLATION
+      # Meanwhile, under the city...
 
-To install this module, run the following commands:
+      # Doesn't explode
+      my $class = My::Class->new(name => undef);
+      $class->has_name # False!
 
-	perl Makefile.PL
-	make
-	make test
-	make install
+    Or, if you only want one attribute to have this behaviour:
 
-SUPPORT AND DOCUMENTATION
+      package My:Class;
+      use Moose;
 
-After installing, you can find documentation for this module with the
-perldoc command.
+      use MooseX::UndefTolerant::Attribute;
 
-    perldoc MooseX::UndefTolerant
+      has 'bar' => (
+          traits => [ qw(MooseX::UndefTolerant::Attribute)],
+          is => 'ro',
+          isa => 'Num',
+          predicate => 'has_bar'
+      );
 
-You can also look for information at:
+DESCRIPTION
+    Loading this module in your 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.
 
-    RT, CPAN's request tracker
-        http://rt.cpan.org/NoAuth/Bugs.html?Dist=MooseX-UndefTolerant
+MOTIVATION
+    I often found myself in this quandry:
 
-    AnnoCPAN, Annotated CPAN documentation
-        http://annocpan.org/dist/MooseX-UndefTolerant
+      package My:Class;
+      use Moose;
 
-    CPAN Ratings
-        http://cpanratings.perl.org/d/MooseX-UndefTolerant
+      has 'foo' => (
+        is => 'ro',
+        isa => 'Str',
+      );
 
-    Search CPAN
-        http://search.cpan.org/dist/MooseX-UndefTolerant/
+      # ... then
 
+      my $foo = ... # get the param from something
 
-COPYRIGHT AND LICENCE
+      my $class = My:Class->new(foo => $foo, bar => 123);
 
-Copyright (C) 2009 Cory G Watson
+    What if foo is undefined? I didn't want to change my attribute to be
+    Maybe[Str] and I still want my predicate ("has_foo") to work. The only
+    real solution was:
 
-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.
+      if(defined($foo)) {
+        $class = My:Class->new(foo => $foo, bar => 123);
+      } else {
+        $class = My:Class->new(bar => 123);
+      }
 
-See http://dev.perl.org/licenses/ for more information.
+    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!
+
+PER ATTRIBUTE
+    See MooseX::UndefTolerant::Attribute.
+
+CAVEATS
+    This extension does not currently work in immutable classes when
+    applying the trait to some (but not all) attributes in the class. This
+    is because the inlined constructor initialization code currently lives
+    in Moose::Meta::Method::Constructor, not Moose::Meta::Attribute. The
+    good news is that this is expected to be changing shortly.
+
+ACKNOWLEDGEMENTS
+    Many thanks to the crew in #moose who talked me through this module:
+
+    Hans Dieter Pearcey (confound)
+
+    Jesse Luehrs (doy)
+
+    Tomas Doran (t0m)
+
+    Dylan Hardison (dylan)
+
+    Jay Shirley (jshirley)
+
+    Mike Eldridge (diz)
+
+AUTHOR
+    Cory G Watson <gphat at cpan.org>
+
+COPYRIGHT AND LICENSE
+    This software is copyright (c) 2011 by Cory G Watson.
+
+    This is free software; you can redistribute it and/or modify it under
+    the same terms as the Perl 5 programming language system itself.