Moose::Manual::Construction - Object construction with Moose |
Moose::Manual::Construction - Object construction (and destruction) with Moose
version 2.1605
Do not define a new()
method for your classes!
When you use Moose
in your class, your class becomes a subclass of
the Moose::Object manpage. The the Moose::Object manpage provides a new()
method for your
class. If you follow our recommendations in the Moose::Manual::BestPractices manpage
and make your class immutable, then you actually get a class-specific new()
method ``inlined'' in your class.
The Moose-provided constructor accepts a hash or hash reference of
named parameters matching your attributes (actually, matching their
init_arg
s). 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!
Moose lets you hook into object construction. You can validate an
object's state, do logging, customize construction from parameters which
do not match your attributes, 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.
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 the Moose::Object manpage. This method takes care of distinguishing between a hash
reference and a plain hash for you.
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}, ) ); }
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
.
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.
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.
Each DEMOLISH
method is called with a single argument. This is a boolean
value indicating whether or not this method was called as part of the global
destruction process (when the Perl interpreter exits).
In most cases, Perl's built-in garbage collection is sufficient, and
you won't need to provide a DEMOLISH
method.
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 the Moose::Object manpage. You can
do this to preserve $@
and capture any errors from object destruction by
creating an error stack.
This software is copyright (c) 2006 by Infinity Interactive, Inc.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
Moose::Manual::Construction - Object construction with Moose |