Rename Extending::Recipe4 to Extending::Mooseish_MooseSugar

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

diff --git a/lib/Moose/Manual/Construction.pod b/lib/Moose/Manual/Construction.pod
index 5048657..55266ec 100644 (file)
--- a/lib/Moose/Manual/Construction.pod
+++ b/lib/Moose/Manual/Construction.pod
@@ -1,17 +1,19 @@
-=pod
+package Moose::Manual::Construction;
+
+# ABSTRACT: Object construction (and destruction) with Moose
 
-=head1 NAME
+__END__
 
-Moose::Manual::Construction - Object construction (and destruction) with Moose
+=pod
 
 =head1 WHERE'S THE CONSTRUCTOR?
 
 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
@@ -37,7 +39,7 @@ be called as part of the object construction process.
 
 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).
@@ -52,25 +54,25 @@ a hash or hash reference. We can use the C<BUILDARGS> method to
 accommodate this calling style:
 
   around BUILDARGS => sub {
-      my $orig = shift;
+      my $orig  = shift;
       my $class = shift;
 
-      if ( @_ == 1 && ! ref $_[0] ) {
-          return $class->$orig(ssn => $_[0]);
+      if ( @_ == 1 && !ref $_[0] ) {
+          return $class->$orig( ssn => $_[0] );
       }
       else {
           return $class->$orig(@_);
       }
   };
 
-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.
+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.
@@ -94,29 +96,27 @@ object creation.
   }
 
 
-As C<BUILD> is called with the original hashref passed to new (or the 
-results of your C<BUILDARGS>, if you have overridden the default 
-C<BUILDARGS>.) it can also use be used to create a custom constructor
-using parameters that weren't consumed by attributes. This can be 
-useful if you need to venture beyond what the default initialization 
-behavior and coercions can accomplish.
-
-       sub BUILD {
-               my $self = shift;
-               my $params_hashref = shift;
-
-               $self->addFriend( My::User->new ($params_hashref->{friendId}, 
-                                                       $params_hashref->{activationCode}) );
-
-       }
+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
@@ -159,17 +159,4 @@ 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>
-
-=head1 COPYRIGHT AND LICENSE
-
-Copyright 2009 by Infinity Interactive, Inc.
-
-L<http://www.iinteractive.com>
-
-This library is free software; you can redistribute it and/or modify
-it under the same terms as Perl itself.
-
 =cut