Use the already-existing anon class caching in MM::Class, rather than implementing...

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

diff --git a/lib/Moose/Manual/Construction.pod b/lib/Moose/Manual/Construction.pod
index 5baad74..60e7cfb 100644 (file)
--- a/lib/Moose/Manual/Construction.pod
+++ b/lib/Moose/Manual/Construction.pod
@@ -50,18 +50,19 @@ Without a C<BUILDARGS> method, Moose will complain, because it expects
 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] };
+          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
+Note the call to C<< $class->$orig >>. 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.
 
@@ -91,6 +92,13 @@ object creation.
       debug( 'Made a new person - SSN = ', $self->ssn, );
   }
 
+Note that while it is not shown here, the C<BUILD> method receives  
+not only the created object, but also a hashref of the original 
+arguments passed to new (or the results of your C<BUILDARGS>, 
+if you have overridden the default C<BUILDARGS>.)  This can be 
+useful if you need to venture beyond what the default 
+initialization behavior and coercions can accomplish.
+
 =head3 BUILD and parent classes
 
 The interaction between multiple C<BUILD> methods in an inheritance
@@ -115,9 +123,29 @@ $self->SUPER::DEMOLISH >>. Moose will arrange for all of the
 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>