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 B<You do not need to 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 C<Moose::Object>, which provides a C<new> method for you. And 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 genreated 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 Sometimes you need to hook into object construction. Some common needs
  28 are validating an object's state, logging, and allowing non-hash(ref)
  29 constructor arguments. Moose provides hooks for these needs with the
  30 C<BUILD> and C<BUILDARGS> methods.
  31
  32 If these are defined in your class, then Moose will arrange for them
  33 to be called as part of the object construction process.
  34
  35 =head2 BUILDARGS
  36
  37 The C<BUILDARGS> method is called I<before> an object is created, and
  38 is therefore called as a class method. It will receive all of the
  39 arguments that were passed to C<new> I<as-is>. Your C<BUILDARGS>
  40 method must then return a hash reference. This hash reference will be
  41 used to construct the object, so it should contain keys matching your
  42 attributes' names (well, C<init_arg>s).
  43
  44 One common use for C<BUILDARGS> is to accomodate 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 accomodate 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 C<Moose::Object>. This method handles distinguishing
  66 between a hash reference and a plain hash, so you don't have to.
  67
  68 =head2 BUILD
  69
  70 The C<BUILD> method is called I<after> an object is created. There are
  71 many potential uses for a C<BUILD> method. One of the most common is
  72 to check that the object state makes sense. While we can validate
  73 individual attributes through the use of types, we can't validate the
  74 state of a 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 =head3 BUILD and Parent Classes
  95
  96 The interaction between multiple C<BUILD> methods in an inheritance
  97 hierarchy is different from normal Perl methods. B<You should never
  98 call C<< $self->SUPER::BUILD >>.>
  99
 100 Moose arranges to have all of the C<BUILD> methods in a hierarchy
 101 called when an object is constructed, I<from parents to
 102 children>. This might be surprising at first, because it reverses the
 103 normal order of method inheritance.
 104
 105 The theory behind this is that C<BUILD> methods can only be used for
 106 increasing specialization of a class's constraints, so it makes sense
 107 to call the least specific first (also, this is how Perl 6 does it).
 108
 109 =head1 OBJECT DESTRUCTION
 110
 111 Moose provides a hook for object destruction with the C<DEMOLISH>
 112 method. As with C<BUILD>, you should never explicitly call C<<
 113 $self->SUPER::DEMOLISH >>. Moose will arrange for all of the
 114 C<DEMOLISH> methods in your hierarchy to be called, from most to least
 115 specific.
 116
 117 In most cases, Perl's built-in garbage collection is sufficient, and
 118 you won't need ot provide a C<DEMOLISH> method.
 119
 120 =head1 AUTHOR
 121
 122 Dave Rolsky E<lt>autarch@urth.orgE<gt>
 123
 124 =head1 COPYRIGHT AND LICENSE
 125
 126 Copyright 2008 by Infinity Interactive, Inc.
 127
 128 L<http://www.iinteractive.com>
 129
 130 This library is free software; you can redistribute it and/or modify
 131 it under the same terms as Perl itself.
 132
 133 =cut