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_arg"s).

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 takes care of 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 reasons 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, );
  }

The "BUILD" method is called with the hash reference of the parameters passed to the constructor (after munging by "BUILDARGS"). This gives you a chance to do something with parameters that do not represent object attributes.

  sub BUILD {
      my $self = shift;
      my $args = shift;
      $self->add_friend(
          My::User->new(
              user_id => $args->{user_id},
          )
      );
  }

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", nor should you ever apply a method modifier to "BUILD". Roles are an exception to this rule, though: it's completely acceptable to apply a method modifier to "BUILD" in a role; you can even provide an empty "BUILD" subroutine in a role so the role is applicable even to classes without their own "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.

Error Handling During Destruction

The interaction of object destruction and Perl's global $@ and $? variables can be very confusing.

Moose always localizes $? when an object is being destroyed. This means that if you explicitly call "exit", that exit code will be preserved even if an object's destructor makes a system call.

Moose also preserves $@ against any "eval" calls that may happen during object destruction. However, if an object's "DEMOLISH" method actually dies, Moose explicitly rethrows that error.

If you do not like this behavior, you will have to provide your own "DESTROY" method and use that instead of the one provided by Moose::Object. You can do this to preserve $@ and capture any errors from object destruction by creating an error stack.