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
  11 my %metaroles = (
  12     class_metaroles => {
  13         attribute => [ 'MooseX::UndefTolerant::Attribute' ],
  14     }
  15 );
  16 if ( $Moose::VERSION < 1.9900 ) {
  17     $metaroles{class_metaroles}{constructor} = [
  18         'MooseX::UndefTolerant::Constructor',
  19     ];
  20 }
  21 else {
  22     $metaroles{class_metaroles}{class} = [
  23         'MooseX::UndefTolerant::Class',
  24     ];
  25     $metaroles{role_metaroles} = {
  26         applied_attribute => [
  27             'MooseX::UndefTolerant::Attribute',
  28         ],
  29         role => [
  30             'MooseX::UndefTolerant::Role',
  31         ],
  32         application_to_class => [
  33             'MooseX::UndefTolerant::ApplicationToClass',
  34         ],
  35         application_to_role => [
  36             'MooseX::UndefTolerant::ApplicationToRole',
  37         ],
  38     };
  39 }
  40
  41
  42 Moose::Exporter->setup_import_methods(%metaroles);
  43
  44 1;
  45
  46 # ABSTRACT: Make your attribute(s) tolerant to undef initialization
  47
  48 __END__
  49
  50 =head1 SYNOPSIS
  51
  52   package My::Class;
  53
  54   use Moose;
  55   use MooseX::UndefTolerant;
  56
  57   has 'name' => (
  58     is => 'ro',
  59     isa => 'Str',
  60     predicate => 'has_name'
  61   );
  62
  63   # Meanwhile, under the city...
  64
  65   # Doesn't explode
  66   my $class = My::Class->new(name => undef);
  67   $class->has_name # False!
  68
  69 Or, if you only want one attribute to have this behaviour:
  70
  71   package My:Class;
  72   use Moose;
  73
  74   use MooseX::UndefTolerant::Attribute;
  75
  76   has 'bar' => (
  77       traits => [ qw(MooseX::UndefTolerant::Attribute)],
  78       is => 'ro',
  79       isa => 'Num',
  80       predicate => 'has_bar'
  81   );
  82
  83 =head1 DESCRIPTION
  84
  85 Loading this module in your L<Moose> class makes initialization of your
  86 attributes tolerant of undef.  If you specify the value of undef to any of
  87 the attributes they will not be initialized, effectively behaving as if you
  88 had not provided a value at all.
  89
  90 You can also apply the 'UndefTolerant' trait to individual attributes. See
  91 L<MooseX::UndefTolerant::Attribute> for details.
  92
  93 There will be no change in behaviour to any attribute with a type constraint
  94 that accepts undef values (for example C<Maybe> types), as it is presumed that
  95 since the type is already "undef tolerant", there is no need to avoid
  96 initializing the attribute value with C<undef>.
  97
  98 As of Moose 1.9900, this module can also be used in a role, in which case all
  99 of that role's attributes will be undef-tolerant.
 100
 101 =head1 MOTIVATION
 102
 103 I often found myself in this quandry:
 104
 105   package My:Class;
 106   use Moose;
 107
 108   has 'foo' => (
 109     is => 'ro',
 110     isa => 'Str',
 111   );
 112
 113   # ... then
 114
 115   my $foo = ... # get the param from something
 116
 117   my $class = My:Class->new(foo => $foo, bar => 123);
 118
 119 What if foo is undefined?  I didn't want to change my attribute to be
 120 Maybe[Str] and I still want my predicate (C<has_foo>) to work.  The only
 121 real solution was:
 122
 123   if(defined($foo)) {
 124     $class = My:Class->new(foo => $foo, bar => 123);
 125   } else {
 126     $class = My:Class->new(bar => 123);
 127   }
 128
 129 Or some type of codemulch using ternary conditionals.  This module allows you
 130 to make your attributes more tolerant of undef so that you can keep the first
 131 example: have your cake and eat it too!
 132
 133 =head1 PER ATTRIBUTE
 134
 135 See L<MooseX::UndefTolerant::Attribute>.
 136
 137 =head1 CAVEATS
 138
 139 This extension does not currently work in immutable classes when applying the
 140 trait to some (but not all) attributes in the class. This is because the
 141 inlined constructor initialization code currently lives in
 142 L<Moose::Meta::Method::Constructor>, not L<Moose::Meta::Attribute>. The good
 143 news is that this is expected to be changing shortly.
 144
 145 =head1 ACKNOWLEDGEMENTS
 146
 147 Many thanks to the crew in #moose who talked me through this module:
 148
 149 Hans Dieter Pearcey (confound)
 150
 151 Jesse Luehrs (doy)
 152
 153 Tomas Doran (t0m)
 154
 155 Dylan Hardison (dylan)
 156
 157 Jay Shirley (jshirley)
 158
 159 Mike Eldridge (diz)
 160
 161 =cut