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, or maybe allow non-hash(ref) constructor
  29 arguments. You can do this by creating C<BUILD> and/or C<BUILDARGS>
  30 methods.
  31
  32 If these methods exist in your class, Moose will arrange for them to
  33 be called as part of the object construction process.
  34
  35 =head2 BUILDARGS
  36
  37 The C<BUILDARGS> method is called as a class method I<before> an
  38 object is created. It will receive all of the arguments that were
  39 passed to C<new> I<as-is>, and is expected to return a hash
  40 reference. This hash reference will be used to construct the object,
  41 so it should contain keys matching your attributes' names (well,
  42 C<init_arg>s).
  43
  44 One common use for C<BUILDARGS> is to accommodate a non-hash(ref)
  45 calling style. For example, we might want to allow our Person class to
  46 be called with a single argument of a social security number, C<<
  47 Person->new($ssn) >>.
  48
  49 Without a C<BUILDARGS> method, Moose will complain, because it expects
  50 a hash or hash reference. We can use the C<BUILDARGS> method to
  51 accommodate this calling style:
  52
  53   sub BUILDARGS {
  54       my $class = shift;
  55
  56       if ( @_ == 1 && ! ref $_[0] ) {
  57           return { ssn => $_[0] };
  58       }
  59       else {
  60           return $class->SUPER::BUILDARGS(@_);
  61       }
  62   }
  63
  64 Note the call to C<SUPER::BUILDARGS>. This will call the default
  65 C<BUILDARGS> in L<Moose::Object>. This method handles distinguishing
  66 between a hash reference and a plain hash for you.
  67
  68 =head2 BUILD
  69
  70 The C<BUILD> method is called I<after> an object is created. There are
  71 several ways to use a C<BUILD> method. One of the most common is to
  72 check that the object state is valid. While we can validate individual
  73 attributes through the use of types, we can't validate the state of a
  74 whole object that way.
  75
  76   sub BUILD {
  77       my $self = shift;
  78
  79       if ( $self->country_of_residence eq 'USA' ) {
  80           die 'All US residents must have an SSN'
  81               unless $self->has_ssn;
  82       }
  83   }
  84
  85 Another use of a C<BUILD> method could be for logging or tracking
  86 object creation.
  87
  88   sub BUILD {
  89       my $self = shift;
  90
  91       debug( 'Made a new person - SSN = ', $self->ssn, );
  92   }
  93
  94 Note that while it is not shown here, the C<BUILD> method receives
  95 not only the created object, but also a hashref of the original
  96 arguments passed to new (or the results of your C<BUILDARGS>,
  97 if you have overridden the default C<BUILDARGS>.)  This can be
  98 useful if you need to venture beyond what the default
  99 initialization behavior and coercions can accomplish.
 100
 101 =head3 BUILD and parent classes
 102
 103 The interaction between multiple C<BUILD> methods in an inheritance
 104 hierarchy is different from normal Perl methods. B<You should never
 105 call C<< $self->SUPER::BUILD >>.>
 106
 107 Moose arranges to have all of the C<BUILD> methods in a hierarchy
 108 called when an object is constructed, I<from parents to
 109 children>. This might be surprising at first, because it reverses the
 110 normal order of method inheritance.
 111
 112 The theory behind this is that C<BUILD> methods can only be used for
 113 increasing specialization of a class's constraints, so it makes sense
 114 to call the least specific C<BUILD> method first. Also, this is how
 115 Perl 6 does it.
 116
 117 =head1 OBJECT DESTRUCTION
 118
 119 Moose provides a hook for object destruction with the C<DEMOLISH>
 120 method. As with C<BUILD>, you should never explicitly call C<<
 121 $self->SUPER::DEMOLISH >>. Moose will arrange for all of the
 122 C<DEMOLISH> methods in your hierarchy to be called, from most to least
 123 specific.
 124
 125 In most cases, Perl's built-in garbage collection is sufficient, and
 126 you won't need to provide a C<DEMOLISH> method.
 127
 128 =head1 AUTHOR
 129
 130 Dave Rolsky E<lt>autarch@urth.orgE<gt>
 131
 132 =head1 COPYRIGHT AND LICENSE
 133
 134 Copyright 2009 by Infinity Interactive, Inc.
 135
 136 L<http://www.iinteractive.com>
 137
 138 This library is free software; you can redistribute it and/or modify
 139 it under the same terms as Perl itself.
 140
 141 =cut