First draft of docs on object construction

[gitmo/Moose.git] / lib / Moose / Manual / Construction.pod

=pod

=head1 NAME

Moose::Manual::Classes - Object construction (and destruction) with Moose

=head1 WHERE'S THE CONSTRUCTOR?

The first question about object construction with Moose might be how
it happens. B<You do not need to define a C<new()> method for your
classes!>

When you C<use Moose> in your class, you will become a subclass of
C<Moose::Object>, which provides a C<new> method for you. And if you
follow our recommendations and make your class immutable, then you
actually get a class-specific C<new> method genreated in your class.

The Moose-provided constructor accepts a hash or hash reference of
named parameters matching your attributes (actually, matching their
C<init_arg>s). This is just another way in which Moose keeps you from
worrying I<how> classes are implemented. Simply define a class and
you're ready to start creating objects!

=head1 DOING "STUFF" WHEN AN OBJECT IS CONSTRUCTED

Sometimes you need to hook into object construction. Some common needs
are validating an object's state, logging, and allowing non-hash(ref)
constructor arguments. Moose provides hooks for these needs with the
C<BUILD> and C<BUILDARGS> methods.

If these are defined in your class, then Moose will arrange for them
to be called as part of the object construction process.

=head2 BUILDARGS

The C<BUILDARGS> method is called I<before> an object is created, and
is therefore called as a class method. It will receive all of the
arguments that were passed to C<new> I<as-is>. Your C<BUILDARGS>
method must then return a hash reference. This hash reference will be
used to construct the object, so it should contain keys matching your
attributes' names (well, C<init_arg>s).

One common use for C<BUILDARGS> is to accomodate a non-hash(ref)
calling style. For example, we might want to allow our Person class to
be called with a single argument of a social security number, C<<
Person->new($ssn) >>.

Without a C<BUILDARGS> method, Moose will complain, because this is
clearly not a hash reference. With a C<BUILDARGS> method we can easily
accomodate this:

  sub BUILDARGS {
      my $class = shift;

      if ( @_ == 1 && ! ref $_[0] ) {
          return { ssn => $_[0] };
      }
      else {
          return $class->SUPER::BUILDARGS(@_);
      }
  }

Note the call to C<SUPER::BUILDARGS>. This will call the default
C<BUILDARGS> in C<Moose::Object>. This method handles distinguishing
between a hash reference and a plain hash, so you don't have to.

=head2 BUILD

The C<BUILD> method is called I<after> an object is created. There are
many potential uses for a C<BUILD> method. One of the most common is
to check that the object state makes sense. While we can validate
individual attributes through the use of types, we can't validate the
state of a whole object that way.

  sub BUILD {
      my $self = shift;

      if ( $self->country_of_residence eq 'USA' ) {
          die 'All US residents must have an SSN'
              unless $self->has_ssn;
      }
  }

Another use of a C<BUILD> method could be for logging or tracking
object creation.

  sub BUILD {
      my $self = shift;

      log_debug( 'Made a new person - SSN = ', $self->ssn, );
  }

=head3 BUILD and Parent Classes

The interaction between multiple C<BUILD> methods in an inheritance
hierarchy is different from normal Perl methods. B<You should never
call C<< $self->SUPER::BUILD >>.>

Moose arranges to have all of the C<BUILD> methods in a hierarchy
called when an object is constructed, I<from parents to
children>. This might be surprising at first, because it reverses the
normal order of method inheritance.

The theory behind this is that C<BUILD> methods can only be used for
increasing specialization of a class's constraints, so it makes sense
to call the least specific first (also, this is how Perl 6 does it).

=head OBJECT DESTRUCTION

Moose provides a hook for object destruction with the C<DEMOLISH>
method. As with C<BUILD>, you should never explicitly call C<<
$self->SUPER::DEMOLISH >>. Moose will arrange for all of the
C<DEMOLISH> methods in your hierarchy to be called, from most to least
specific.

=head1 AUTHOR

Dave Rolsky E<lt>autarch@urth.orgE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright 2008 by Infinity Interactive, Inc.

L<http://www.iinteractive.com>

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

=cut