lib/Moose/Manual/Construction.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 Moose::Manual::Construction - Object construction (and destruction) with Moose
   6
   7 =head1 WHERE'S THE CONSTRUCTOR?
   8
   9 B<Do not define a C<new()> method for your classes!>
  10
  11 When you C<use Moose> in your class, you will become a subclass of
  12 L<Moose::Object>, which provides a C<new> method for you. If you
  13 follow our recommendations in L<Moose::Manual::BestPractices> and make
  14 your class immutable, then you actually get a class-specific C<new>
  15 method "inlined" in your class.
  16
  17 =head1 OBJECT CONSTRUCTION AND ATTRIBUTES
  18
  19 The Moose-provided constructor accepts a hash or hash reference of
  20 named parameters matching your attributes (actually, matching their
  21 C<init_arg>s). This is just another way in which Moose keeps you from
  22 worrying I<how> classes are implemented. Simply define a class and
  23 you're ready to start creating objects!
  24
  25 =head1 OBJECT CONSTRUCTION HOOKS
  26
  27 Moose lets you hook into object construction. You can validate an
  28 object's state, do logging, customize construction from parameters which
  29 do not match your attributes, or maybe allow non-hash(ref) constructor
  30 arguments. You can do this by creating C<BUILD> and/or C<BUILDARGS>
  31 methods.
  32
  33 If these methods exist in your class, Moose will arrange for them to
  34 be called as part of the object construction process.
  35
  36 =head2 BUILDARGS
  37
  38 The C<BUILDARGS> method is called as a class method I<before> an
  39 object is created. It will receive all of the arguments that were
  40 passed to C<new> I<as-is>, and is expected to return a hash
  41 reference. This hash reference will be used to construct the object,
  42 so it should contain keys matching your attributes' names (well,
  43 C<init_arg>s).
  44
  45 One common use for C<BUILDARGS> is to accommodate a non-hash(ref)
  46 calling style. For example, we might want to allow our Person class to
  47 be called with a single argument of a social security number, C<<
  48 Person->new($ssn) >>.
  49
  50 Without a C<BUILDARGS> method, Moose will complain, because it expects
  51 a hash or hash reference. We can use the C<BUILDARGS> method to
  52 accommodate this calling style:
  53
  54   around BUILDARGS => sub {
  55       my $orig = shift;
  56       my $class = shift;
  57
  58       if ( @_ == 1 && ! ref $_[0] ) {
  59           return $class->$orig(ssn => $_[0]);
  60       }
  61       else {
  62           return $class->$orig(@_);
  63       }
  64   };
  65
  66 Note the call to C<< $class->$orig >>. This will call the default
  67 C<BUILDARGS> in L<Moose::Object>. This method handles distinguishing
  68 between a hash reference and a plain hash for you.
  69
  70 =head2 BUILD
  71
  72 The C<BUILD> method is called I<after> an object is created. There are
  73 several ways to use a C<BUILD> method. One of the most common is to
  74 check that the object state is valid. While we can validate individual
  75 attributes through the use of types, we can't validate the state of a
  76 whole object that way.
  77
  78   sub BUILD {
  79       my $self = shift;
  80
  81       if ( $self->country_of_residence eq 'USA' ) {
  82           die 'All US residents must have an SSN'
  83               unless $self->has_ssn;
  84       }
  85   }
  86
  87 Another use of a C<BUILD> method could be for logging or tracking
  88 object creation.
  89
  90   sub BUILD {
  91       my $self = shift;
  92
  93       debug( 'Made a new person - SSN = ', $self->ssn, );
  94   }
  95
  96
  97 As C<BUILD> is called with the original hashref passed to new (or the
  98 results of your C<BUILDARGS>, if you have overridden the default
  99 C<BUILDARGS>.) it can also use be used to create a custom constructor
 100 using parameters that weren't consumed by attributes. This can be
 101 useful if you need to venture beyond what the default initialization
 102 behavior and coercions can accomplish.
 103
 104   sub BUILD {
 105     my $self = shift;
 106     my $params_hashref = shift;
 107
 108     $self->addFriend( My::User->new ($params_hashref->{friendId},
 109       $params_hashref->{activationCode}) );
 110   }
 111
 112
 113
 114 =head3 BUILD and parent classes
 115
 116 The interaction between multiple C<BUILD> methods in an inheritance
 117 hierarchy is different from normal Perl methods. B<You should never
 118 call C<< $self->SUPER::BUILD >>.>
 119
 120 Moose arranges to have all of the C<BUILD> methods in a hierarchy
 121 called when an object is constructed, I<from parents to
 122 children>. This might be surprising at first, because it reverses the
 123 normal order of method inheritance.
 124
 125 The theory behind this is that C<BUILD> methods can only be used for
 126 increasing specialization of a class's constraints, so it makes sense
 127 to call the least specific C<BUILD> method first. Also, this is how
 128 Perl 6 does it.
 129
 130 =head1 OBJECT DESTRUCTION
 131
 132 Moose provides a hook for object destruction with the C<DEMOLISH>
 133 method. As with C<BUILD>, you should never explicitly call C<<
 134 $self->SUPER::DEMOLISH >>. Moose will arrange for all of the
 135 C<DEMOLISH> methods in your hierarchy to be called, from most to least
 136 specific.
 137
 138 Each C<DEMOLISH> method is called with a single argument.
 139
 140 In most cases, Perl's built-in garbage collection is sufficient, and
 141 you won't need to provide a C<DEMOLISH> method.
 142
 143 =head2 Error Handling During Destruction
 144
 145 The interaction of object destruction and Perl's global C<$@> and C<$?>
 146 variables can be very confusing.
 147
 148 Moose always localizes C<$?> when an object is being destroyed. This means
 149 that if you explicitly call C<exit>, that exit code will be preserved even if
 150 an object's destructor makes a system call.
 151
 152 Moose also preserves C<$@> against any C<eval> calls that may happen during
 153 object destruction. However, if an object's C<DEMOLISH> method actually dies,
 154 Moose explicitly rethrows that error.
 155
 156 If you do not like this behavior, you will have to provide your own C<DESTROY>
 157 method and use that instead of the one provided by L<Moose::Object>. You can
 158 do this to preserve C<$@> I<and> capture any errors from object destruction by
 159 creating an error stack.
 160
 161 =head1 AUTHOR
 162
 163 Dave Rolsky E<lt>autarch@urth.orgE<gt>
 164
 165 =head1 COPYRIGHT AND LICENSE
 166
 167 Copyright 2009 by Infinity Interactive, Inc.
 168
 169 L<http://www.iinteractive.com>
 170
 171 This library is free software; you can redistribute it and/or modify
 172 it under the same terms as Perl itself.
 173
 174 =cut