lib/Moose/Manual/Construction.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 Moose::Manual::Classes - Object construction (and destruction) with Moose
   6
   7 =head1 WHERE'S THE CONSTRUCTOR?
   8
   9 The first question about object construction with Moose might be how
  10 it happens. B<You do not need to define a C<new()> method for your
  11 classes!>
  12
  13 When you C<use Moose> in your class, you will become a subclass of
  14 C<Moose::Object>, which provides a C<new> method for you. And if you
  15 follow our recommendations and make your class immutable, then you
  16 actually get a class-specific C<new> method genreated in your class.
  17
  18 The Moose-provided constructor accepts a hash or hash reference of
  19 named parameters matching your attributes (actually, matching their
  20 C<init_arg>s). This is just another way in which Moose keeps you from
  21 worrying I<how> classes are implemented. Simply define a class and
  22 you're ready to start creating objects!
  23
  24 =head1 DOING "STUFF" WHEN AN OBJECT IS CONSTRUCTED
  25
  26 Sometimes you need to hook into object construction. Some common needs
  27 are validating an object's state, logging, and allowing non-hash(ref)
  28 constructor arguments. Moose provides hooks for these needs with the
  29 C<BUILD> and C<BUILDARGS> methods.
  30
  31 If these are defined in your class, then Moose will arrange for them
  32 to be called as part of the object construction process.
  33
  34 =head2 BUILDARGS
  35
  36 The C<BUILDARGS> method is called I<before> an object is created, and
  37 is therefore called as a class method. It will receive all of the
  38 arguments that were passed to C<new> I<as-is>. Your C<BUILDARGS>
  39 method must then return a hash reference. This hash reference will be
  40 used to construct the object, so it should contain keys matching your
  41 attributes' names (well, C<init_arg>s).
  42
  43 One common use for C<BUILDARGS> is to accomodate a non-hash(ref)
  44 calling style. For example, we might want to allow our Person class to
  45 be called with a single argument of a social security number, C<<
  46 Person->new($ssn) >>.
  47
  48 Without a C<BUILDARGS> method, Moose will complain, because this is
  49 clearly not a hash reference. With a C<BUILDARGS> method we can easily
  50 accomodate this:
  51
  52   sub BUILDARGS {
  53       my $class = shift;
  54
  55       if ( @_ == 1 && ! ref $_[0] ) {
  56           return { ssn => $_[0] };
  57       }
  58       else {
  59           return $class->SUPER::BUILDARGS(@_);
  60       }
  61   }
  62
  63 Note the call to C<SUPER::BUILDARGS>. This will call the default
  64 C<BUILDARGS> in C<Moose::Object>. This method handles distinguishing
  65 between a hash reference and a plain hash, so you don't have to.
  66
  67 =head2 BUILD
  68
  69 The C<BUILD> method is called I<after> an object is created. There are
  70 many potential uses for a C<BUILD> method. One of the most common is
  71 to check that the object state makes sense. While we can validate
  72 individual attributes through the use of types, we can't validate the
  73 state of a whole object that way.
  74
  75   sub BUILD {
  76       my $self = shift;
  77
  78       if ( $self->country_of_residence eq 'USA' ) {
  79           die 'All US residents must have an SSN'
  80               unless $self->has_ssn;
  81       }
  82   }
  83
  84 Another use of a C<BUILD> method could be for logging or tracking
  85 object creation.
  86
  87   sub BUILD {
  88       my $self = shift;
  89
  90       log_debug( 'Made a new person - SSN = ', $self->ssn, );
  91   }
  92
  93 =head3 BUILD and Parent Classes
  94
  95 The interaction between multiple C<BUILD> methods in an inheritance
  96 hierarchy is different from normal Perl methods. B<You should never
  97 call C<< $self->SUPER::BUILD >>.>
  98
  99 Moose arranges to have all of the C<BUILD> methods in a hierarchy
 100 called when an object is constructed, I<from parents to
 101 children>. This might be surprising at first, because it reverses the
 102 normal order of method inheritance.
 103
 104 The theory behind this is that C<BUILD> methods can only be used for
 105 increasing specialization of a class's constraints, so it makes sense
 106 to call the least specific first (also, this is how Perl 6 does it).
 107
 108 =head OBJECT DESTRUCTION
 109
 110 Moose provides a hook for object destruction with the C<DEMOLISH>
 111 method. As with C<BUILD>, you should never explicitly call C<<
 112 $self->SUPER::DEMOLISH >>. Moose will arrange for all of the
 113 C<DEMOLISH> methods in your hierarchy to be called, from most to least
 114 specific.
 115
 116 =head1 AUTHOR
 117
 118 Dave Rolsky E<lt>autarch@urth.orgE<gt>
 119
 120 =head1 COPYRIGHT AND LICENSE
 121
 122 Copyright 2008 by Infinity Interactive, Inc.
 123
 124 L<http://www.iinteractive.com>
 125
 126 This library is free software; you can redistribute it and/or modify
 127 it under the same terms as Perl itself.
 128
 129 =cut