NAME

       Moose::Manual::Construction - Object construction (and destruction) with Moose

VERSION

       version 2.1005

WHERE'S THE CONSTRUCTOR?

       Do not define a "new()" method for your classes!

       When you "use Moose" in your class, your class becomes a subclass of Moose::Object. The
       Moose::Object provides a "new()" method for your class. If you follow our recommendations
       in Moose::Manual::BestPractices and make your class immutable, then you actually get a
       class-specific "new()" method "inlined" in your class.

OBJECT CONSTRUCTION AND ATTRIBUTES

       The Moose-provided constructor accepts a hash or hash reference of named parameters
       matching your attributes (actually, matching their "init_arg"s). This is just another way
       in which Moose keeps you from worrying how classes are implemented. Simply define a class
       and you're ready to start creating objects!

OBJECT CONSTRUCTION HOOKS

       Moose lets you hook into object construction. You can validate an 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 "BUILD"
       and/or "BUILDARGS" methods.

       If these methods exist in your class, Moose will arrange for them to be called as part of
       the object construction process.

   BUILDARGS
       The "BUILDARGS" method is called as a class method before an object is created. It will
       receive all of the arguments that were passed to "new()" 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, "init_arg"s).

       One common use for "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, "Person->new($ssn)".

       Without a "BUILDARGS" method, Moose will complain, because it expects a hash or hash
       reference. We can use the "BUILDARGS" method to accommodate this calling style:

         around BUILDARGS => sub {
             my $orig  = shift;
             my $class = shift;

             if ( @_ == 1 && !ref $_[0] ) {
                 return $class->$orig( ssn => $_[0] );
             }
             else {
                 return $class->$orig(@_);
             }
         };

       Note the call to "$class->$orig". This will call the default "BUILDARGS" in Moose::Object.
       This method takes care of distinguishing between a hash reference and a plain hash for
       you.

   BUILD
       The "BUILD" method is called after an object is created. There are several reasons to use
       a "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;

             if ( $self->country_of_residence eq 'USA' ) {
                 die 'All US residents must have an SSN'
                     unless $self->has_ssn;
             }
         }

       Another use of a "BUILD" method could be for logging or tracking object creation.

         sub BUILD {
             my $self = shift;

             debug( 'Made a new person - SSN = ', $self->ssn, );
         }

       The "BUILD" method is called with the hash reference of the parameters passed to the
       constructor (after munging by "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},
                 )
             );
         }

       BUILD and parent classes

       The interaction between multiple "BUILD" methods in an inheritance hierarchy is different
       from normal Perl methods. You should never call "$self->SUPER::BUILD", nor should you ever
       apply a method modifier to "BUILD".

       Moose arranges to have all of the "BUILD" methods in a hierarchy called when an object is
       constructed, 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 "BUILD" methods can only be used for increasing
       specialization of a class's constraints, so it makes sense to call the least specific
       "BUILD" method first. Also, this is how Perl 6 does it.

OBJECT DESTRUCTION

       Moose provides a hook for object destruction with the "DEMOLISH" method. As with "BUILD",
       you should never explicitly call "$self->SUPER::DEMOLISH". Moose will arrange for all of
       the "DEMOLISH" methods in your hierarchy to be called, from most to least specific.

       Each "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 "DEMOLISH" method.

   Error Handling During Destruction
       The interaction of object destruction and Perl's global $@ and $?  variables can be very
       confusing.

       Moose always localizes $? when an object is being destroyed. This means that if you
       explicitly call "exit", that exit code will be preserved even if an object's destructor
       makes a system call.

       Moose also preserves $@ against any "eval" calls that may happen during object
       destruction. However, if an object's "DEMOLISH" method actually dies, Moose explicitly
       rethrows that error.

       If you do not like this behavior, you will have to provide your own "DESTROY" method and
       use that instead of the one provided by Moose::Object. You can do this to preserve $@ and
       capture any errors from object destruction by creating an error stack.

AUTHOR

       Moose is maintained by the Moose Cabal, along with the help of many contributors. See
       "CABAL" in Moose and "CONTRIBUTORS" in Moose for details.

COPYRIGHT AND LICENSE

       This software is copyright (c) 2013 by Infinity Interactive, Inc..

       This is free software; you can redistribute it and/or modify it under the same terms as
       the Perl 5 programming language system itself.