First draft of docs on object construction

diff --git a/lib/Moose/Manual/Construction.pod b/lib/Moose/Manual/Construction.pod
new file mode 100644 (file)
index 0000000..219d4a3
--- /dev/null
+++ b/lib/Moose/Manual/Construction.pod
@@ -0,0 +1,129 @@
+=pod
+
+=head1 NAME
+
+Moose::Manual::Classes - Object construction (and destruction) with Moose
+
+=head1 WHERE'S THE CONSTRUCTOR?
+
+The first question about object construction with Moose might be how
+it happens. B<You do not need to define a C<new()> method for your
+classes!>
+
+When you C<use Moose> in your class, you will become a subclass of
+C<Moose::Object>, which provides a C<new> method for you. And if you
+follow our recommendations and make your class immutable, then you
+actually get a class-specific C<new> method genreated in your class.
+
+The Moose-provided constructor accepts a hash or hash reference of
+named parameters matching your attributes (actually, matching their
+C<init_arg>s). This is just another way in which Moose keeps you from
+worrying I<how> classes are implemented. Simply define a class and
+you're ready to start creating objects!
+
+=head1 DOING "STUFF" WHEN AN OBJECT IS CONSTRUCTED
+
+Sometimes you need to hook into object construction. Some common needs
+are validating an object's state, logging, and allowing non-hash(ref)
+constructor arguments. Moose provides hooks for these needs with the
+C<BUILD> and C<BUILDARGS> methods.
+
+If these are defined in your class, then Moose will arrange for them
+to be called as part of the object construction process.
+
+=head2 BUILDARGS
+
+The C<BUILDARGS> method is called I<before> an object is created, and
+is therefore called as a class method. It will receive all of the
+arguments that were passed to C<new> I<as-is>. Your C<BUILDARGS>
+method must then 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).
+
+One common use for C<BUILDARGS> is to accomodate 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, C<<
+Person->new($ssn) >>.
+
+Without a C<BUILDARGS> method, Moose will complain, because this is
+clearly not a hash reference. With a C<BUILDARGS> method we can easily
+accomodate this:
+
+  sub BUILDARGS {
+      my $class = shift;
+
+      if ( @_ == 1 && ! ref $_[0] ) {
+          return { ssn => $_[0] };
+      }
+      else {
+          return $class->SUPER::BUILDARGS(@_);
+      }
+  }
+
+Note the call to C<SUPER::BUILDARGS>. This will call the default
+C<BUILDARGS> in C<Moose::Object>. This method handles distinguishing
+between a hash reference and a plain hash, so you don't have to.
+
+=head2 BUILD
+
+The C<BUILD> method is called I<after> an object is created. There are
+many potential uses for a C<BUILD> method. One of the most common is
+to check that the object state makes sense. 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 C<BUILD> method could be for logging or tracking
+object creation.
+
+  sub BUILD {
+      my $self = shift;
+
+      log_debug( 'Made a new person - SSN = ', $self->ssn, );
+  }
+
+=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 >>.>
+
+Moose arranges to have all of the C<BUILD> methods in a hierarchy
+called when an object is constructed, I<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 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).
+
+=head OBJECT DESTRUCTION
+
+Moose provides a hook for object destruction with the C<DEMOLISH>
+method. As with C<BUILD>, you should never explicitly call C<<
+$self->SUPER::DEMOLISH >>. Moose will arrange for all of the
+C<DEMOLISH> methods in your hierarchy to be called, from most to least
+specific.
+
+=head1 AUTHOR
+
+Dave Rolsky E<lt>autarch@urth.orgE<gt>
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 2008 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