=head1 NAME
-Moose::Manual::Classes - Object construction (and destruction) with Moose
+Moose::Manual::Construction - 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!>
+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.
+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>
+method "inlined" in your class.
+
+=head1 OBJECT CONSTRUCTION AND ATTRIBUTES
The Moose-provided constructor accepts a hash or hash reference of
named parameters matching your attributes (actually, matching their
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
+=head1 OBJECT CONSTRUCTION HOOKS
-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.
+Moose lets you hook into object construction. You can validate an
+object's state, do logging, or maybe allow non-hash(ref) constructor
+arguments. You can do this by creating C<BUILD> and/or 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.
+If these methods exist in your class, 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).
+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
+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)
+One common use for C<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, 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:
+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 {
my $class = shift;
}
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.
+C<BUILDARGS> in L<Moose::Object>. This method handles 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
-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.
+ways 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.
sub BUILD {
my $self = shift;
sub BUILD {
my $self = shift;
- log_debug( 'Made a new person - SSN = ', $self->ssn, );
+ debug( 'Made a new person - SSN = ', $self->ssn, );
}
-=head3 BUILD and Parent Classes
+=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
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
+=head1 OBJECT DESTRUCTION
Moose provides a hook for object destruction with the C<DEMOLISH>
method. As with C<BUILD>, you should never explicitly call C<<
C<DEMOLISH> methods in your hierarchy to be called, from most to least
specific.
+In most cases, Perl's built-in garbage collection is sufficient, and
+you won't need to provide a C<DEMOLISH> method.
+
=head1 AUTHOR
Dave Rolsky E<lt>autarch@urth.orgE<gt>
=head1 COPYRIGHT AND LICENSE
-Copyright 2008 by Infinity Interactive, Inc.
+Copyright 2009 by Infinity Interactive, Inc.
L<http://www.iinteractive.com>
projects / gitmo/Moose.git / blobdiff