NAME

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

WHERE'S THE CONSTRUCTOR?

Do not define a new() method for your classes!

When you use Moose in your class, you will become a subclass of Moose::Object, which provides a new method for you. If you follow our recommendations in Moose::Manual::BestPractices and make your class immutable, then you actually get a class-specific new method "inlined" in your class.

OBJECT CONSTRUCTION AND ATTRIBUTES

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

OBJECT CONSTRUCTION HOOKS

Moose lets you hook into object construction. You can validate an object's state, do logging, or maybe allow non-hash(ref) constructor arguments. You can do this by creating BUILD and/or BUILDARGS methods.

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

BUILDARGS

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

One common use for BUILDARGS is to accommodate 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, Person->new($ssn).

Without a BUILDARGS method, Moose will complain, because it expects a hash or hash reference. We can use the BUILDARGS method to accommodate this calling style:

  around BUILDARGS => sub {
      my $orig = shift;
      my $class = shift;

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

Note the call to $class->$orig. This will call the default BUILDARGS in Moose::Object. This method handles distinguishing between a hash reference and a plain hash for you.

BUILD

The BUILD method is called after an object is created. There are several ways to use a BUILD method. One of the most common is to check that the object state is valid. 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 BUILD method could be for logging or tracking object creation.

  sub BUILD {
      my $self = shift;

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

Note that while it is not shown here, the BUILD method receives not only the created object, but also a hashref of the original arguments passed to new (or the results of your BUILDARGS, if you have overridden the default BUILDARGS.) This can be useful if you need to venture beyond what the default initialization behavior and coercions can accomplish.

BUILD and parent classes

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

Moose arranges to have all of the BUILD methods in a hierarchy called when an object is constructed, 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 BUILD methods can only be used for increasing specialization of a class's constraints, so it makes sense to call the least specific BUILD method first. Also, this is how Perl 6 does it.

OBJECT DESTRUCTION

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

In most cases, Perl's built-in garbage collection is sufficient, and you won't need to provide a DEMOLISH method.

AUTHOR

Dave Rolsky <autarch@urth.org>

COPYRIGHT AND LICENSE

Copyright 2009 by Infinity Interactive, Inc.

http://www.iinteractive.com

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