=head1 WHERE'S THE CONSTRUCTOR?
-B<You do not need to define a C<new()> method for your classes!>
+B<Do not define a C<new()> method for your classes!>
-When you C<use Moose> in your class, you will become a subclass of
-L<Moose::Object>, which provides a C<new> method for you. If you
-follow our recommendations in L<Moose::Manual::BestPractices> and make
-your class immutable, then you actually get a class-specific C<new>
+When you C<use Moose> in your class, your class becomes a subclass of
+L<Moose::Object>. The L<Moose::Object> provides a C<new()> method for your
+class. If you follow our recommendations in L<Moose::Manual::BestPractices>
+and make your class immutable, then you actually get a class-specific C<new()>
method "inlined" in your class.
=head1 OBJECT CONSTRUCTION AND ATTRIBUTES
=head1 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
+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 C<BUILD> and/or C<BUILDARGS>
methods.
The C<BUILDARGS> method is called as a class method I<before> an
object is created. It will receive all of the arguments that were
-passed to C<new> I<as-is>, and is expected to return a hash
+passed to C<new()> I<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,
C<init_arg>s).
a hash or hash reference. We can use the C<BUILDARGS> method to
accommodate this calling style:
- sub BUILDARGS {
+ around BUILDARGS => sub {
+ my $orig = shift;
my $class = shift;
- if ( @_ == 1 && ! ref $_[0] ) {
- return { ssn => $_[0] };
+ if ( @_ == 1 && !ref $_[0] ) {
+ return $class->$orig( ssn => $_[0] );
}
else {
- return $class->SUPER::BUILDARGS(@_);
+ return $class->$orig(@_);
}
- }
+ };
-Note the call to C<SUPER::BUILDARGS>. This will call the default
-C<BUILDARGS> in L<Moose::Object>. This method handles distinguishing
-between a hash reference and a plain hash for you.
+Note the call to C<< $class->$orig >>. This will call the default C<BUILDARGS>
+in L<Moose::Object>. This method takes care of distinguishing between a hash
+reference and a plain hash for you.
=head2 BUILD
The C<BUILD> method is called I<after> an object is created. There are
-several ways to use a C<BUILD> method. One of the most common is to
+several reasons to use a C<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.
debug( 'Made a new person - SSN = ', $self->ssn, );
}
+
+The C<BUILD> method is called with the hash reference of the parameters passed
+to the constructor (after munging by C<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},
+ )
+ );
+ }
+
=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 >>.>
+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 >>>, nor should you ever apply a method modifier to
+C<BUILD>.
Moose arranges to have all of the C<BUILD> methods in a hierarchy
called when an object is constructed, I<from parents to
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).
+to call the least specific C<BUILD> method first. Also, this is how
+Perl 6 does it.
=head1 OBJECT DESTRUCTION
C<DEMOLISH> methods in your hierarchy to be called, from most to least
specific.
+Each C<DEMOLISH> method is called with a single argument.
+
In most cases, Perl's built-in garbage collection is sufficient, and
you won't need to provide a C<DEMOLISH> method.
+=head2 Error Handling During Destruction
+
+The interaction of object destruction and Perl's global C<$@> and C<$?>
+variables can be very confusing.
+
+Moose always localizes C<$?> when an object is being destroyed. This means
+that if you explicitly call C<exit>, that exit code will be preserved even if
+an object's destructor makes a system call.
+
+Moose also preserves C<$@> against any C<eval> calls that may happen during
+object destruction. However, if an object's C<DEMOLISH> method actually dies,
+Moose explicitly rethrows that error.
+
+If you do not like this behavior, you will have to provide your own C<DESTROY>
+method and use that instead of the one provided by L<Moose::Object>. You can
+do this to preserve C<$@> I<and> capture any errors from object destruction by
+creating an error stack.
+
=head1 AUTHOR
Dave Rolsky E<lt>autarch@urth.orgE<gt>
projects / gitmo/Moose.git / blobdiff