lib/MooseX/UndefTolerant.pm

   1 package MooseX::UndefTolerant;
   2
   3 use Moose qw();
   4 use Moose::Exporter;
   5
   6 use MooseX::UndefTolerant::Attribute;
   7 use MooseX::UndefTolerant::Class;
   8 use MooseX::UndefTolerant::Constructor;
   9
  10 our $VERSION = '0.09';
  11
  12 my %metaroles = ( attribute => [ 'MooseX::UndefTolerant::Attribute' ] );
  13 if ( $Moose::VERSION < 1.9900 ) {
  14         $metaroles{constructor} = [ 'MooseX::UndefTolerant::Constructor' ];
  15 }
  16 else {
  17         $metaroles{class} = [ 'MooseX::UndefTolerant::Class' ];
  18 }
  19
  20
  21 Moose::Exporter->setup_import_methods(
  22     class_metaroles => \%metaroles,
  23 );
  24
  25 1;
  26
  27 __END__
  28
  29 =head1 NAME
  30
  31 MooseX::UndefTolerant - Make your attribute(s) tolerant to undef initialization
  32
  33 =head1 SYNOPSIS
  34
  35   package My::Class;
  36
  37   use Moose;
  38   use MooseX::UndefTolerant;
  39
  40   has 'name' => (
  41     is => 'ro',
  42     isa => 'Str',
  43     predicate => 'has_name'
  44   );
  45
  46   # Meanwhile, under the city...
  47
  48   # Doesn't explode
  49   my $class = My::Class->new(name => undef);
  50   $class->has_name # False!
  51
  52 Or, if you only want one attribute to have this behaviour:
  53
  54   package My:Class;
  55   use Moose;
  56
  57   use MooseX::UndefTolerant::Attribute;
  58
  59   has 'bar' => (
  60       traits => [ qw(MooseX::UndefTolerant::Attribute)],
  61       is => 'ro',
  62       isa => 'Num',
  63       predicate => 'has_bar'
  64   );
  65
  66 =head1 DESCRIPTION
  67
  68 Loading this module in your L<Moose> class makes initialization of your
  69 attributes tolerant of undef.  If you specify the value of undef to any of
  70 the attributes they will not be initialized, effectively behaving as if you
  71 had not provided a value at all.
  72
  73 =head1 MOTIVATION
  74
  75 I often found myself in this quandry:
  76
  77   package My:Class;
  78   use Moose;
  79
  80   has 'foo' => (
  81     is => 'ro',
  82     isa => 'Str',
  83   );
  84
  85   # ... then
  86
  87   my $foo = ... # get the param from something
  88
  89   my $class = My:Class->new(foo => $foo, bar => 123);
  90
  91 What if foo is undefined?  I didn't want to change my attribute to be
  92 Maybe[Str] and I still want my predicate (C<has_foo>) to work.  The only
  93 real solution was:
  94
  95   if(defined($foo)) {
  96     $class = My:Class->new(foo => $foo, bar => 123);
  97   } else {
  98     $class = My:Class->new(bar => 123);
  99   }
 100
 101 Or some type of codemulch using ternarys.  This module allows you to make
 102 your attributes more tolerant of undef so that you can keep the first
 103 example: have your cake and eat it too!
 104
 105 =head1 PER ATTRIBUTE
 106
 107 See L<MooseX::UndefTolerant::Attribute>.
 108
 109 =head1 CAVEATS
 110
 111 This extension does not currently work in immutable classes when applying the
 112 trait to some (but not all) attributes in the class. This is because the
 113 inlined constructor initialization code currently lives in
 114 L<Moose::Meta::Method::Constructor>, not L<Moose::Meta::Attribute>. The good
 115 news is that this is expected to be changing shortly.
 116
 117 =head1 AUTHOR
 118
 119 Cory G Watson, C<< <gphat at cpan.org> >>
 120
 121 =head1 ACKNOWLEDGEMENTS
 122
 123 Many thanks to the crew in #moose who talked me through this module:
 124
 125 Hans Dieter Pearcey (confound)
 126
 127 Jesse Luehrs (doy)
 128
 129 Tomas Doran (t0m)
 130
 131 Dylan Hardison (dylan)
 132
 133 Jay Shirley (jshirley)
 134
 135 Mike Eldridge (diz)
 136
 137 =head1 COPYRIGHT & LICENSE
 138
 139 Copyright 2009 Cory G Watson.
 140
 141 This program is free software; you can redistribute it and/or modify it
 142 under the terms of either: the GNU General Public License as published
 143 by the Free Software Foundation; or the Artistic License.
 144
 145 See http://dev.perl.org/licenses/ for more information.
 146
 147 =cut