5 Moose::Manual::Classes - Object construction (and destruction) with Moose
7 =head1 WHERE'S THE CONSTRUCTOR?
9 B<You do not need to define a C<new()> method for your classes!>
11 When you C<use Moose> in your class, you will become a subclass of
12 C<Moose::Object>, which provides a C<new> method for you. And if you
13 follow our recommendations in L<Moose::Manual::BestPractices> and make
14 your class immutable, then you actually get a class-specific C<new>
15 method genreated in your class.
17 The Moose-provided constructor accepts a hash or hash reference of
18 named parameters matching your attributes (actually, matching their
19 C<init_arg>s). This is just another way in which Moose keeps you from
20 worrying I<how> classes are implemented. Simply define a class and
21 you're ready to start creating objects!
23 =head1 OBJECT CONSTRUCTION HOOKS
25 Sometimes you need to hook into object construction. Some common needs
26 are validating an object's state, logging, and allowing non-hash(ref)
27 constructor arguments. Moose provides hooks for these needs with the
28 C<BUILD> and C<BUILDARGS> methods.
30 If these are defined in your class, then Moose will arrange for them
31 to be called as part of the object construction process.
35 The C<BUILDARGS> method is called I<before> an object is created, and
36 is therefore called as a class method. It will receive all of the
37 arguments that were passed to C<new> I<as-is>. Your C<BUILDARGS>
38 method must then return a hash reference. This hash reference will be
39 used to construct the object, so it should contain keys matching your
40 attributes' names (well, C<init_arg>s).
42 One common use for C<BUILDARGS> is to accomodate a non-hash(ref)
43 calling style. For example, we might want to allow our Person class to
44 be called with a single argument of a social security number, C<<
47 Without a C<BUILDARGS> method, Moose will complain, because it expects
48 a hash or hash reference. We can use the C<BUILDARGS> method to
49 accomodate this calling style:
54 if ( @_ == 1 && ! ref $_[0] ) {
55 return { ssn => $_[0] };
58 return $class->SUPER::BUILDARGS(@_);
62 Note the call to C<SUPER::BUILDARGS>. This will call the default
63 C<BUILDARGS> in C<Moose::Object>. This method handles distinguishing
64 between a hash reference and a plain hash, so you don't have to.
68 The C<BUILD> method is called I<after> an object is created. There are
69 many potential uses for a C<BUILD> method. One of the most common is
70 to check that the object state makes sense. While we can validate
71 individual attributes through the use of types, we can't validate the
72 state of a whole object that way.
77 if ( $self->country_of_residence eq 'USA' ) {
78 die 'All US residents must have an SSN'
79 unless $self->has_ssn;
83 Another use of a C<BUILD> method could be for logging or tracking
89 debug( 'Made a new person - SSN = ', $self->ssn, );
92 =head3 BUILD and Parent Classes
94 The interaction between multiple C<BUILD> methods in an inheritance
95 hierarchy is different from normal Perl methods. B<You should never
96 call C<< $self->SUPER::BUILD >>.>
98 Moose arranges to have all of the C<BUILD> methods in a hierarchy
99 called when an object is constructed, I<from parents to
100 children>. This might be surprising at first, because it reverses the
101 normal order of method inheritance.
103 The theory behind this is that C<BUILD> methods can only be used for
104 increasing specialization of a class's constraints, so it makes sense
105 to call the least specific first (also, this is how Perl 6 does it).
107 =head1 OBJECT DESTRUCTION
109 Moose provides a hook for object destruction with the C<DEMOLISH>
110 method. As with C<BUILD>, you should never explicitly call C<<
111 $self->SUPER::DEMOLISH >>. Moose will arrange for all of the
112 C<DEMOLISH> methods in your hierarchy to be called, from most to least
115 In most cases, Perl's built-in garbage collection is sufficient, and
116 you won't need ot provide a C<DEMOLISH> method.
120 Dave Rolsky E<lt>autarch@urth.orgE<gt>
122 =head1 COPYRIGHT AND LICENSE
124 Copyright 2008 by Infinity Interactive, Inc.
126 L<http://www.iinteractive.com>
128 This library is free software; you can redistribute it and/or modify
129 it under the same terms as Perl itself.