close over the coercion sub separately
[gitmo/Moose.git] / lib / Moose / Manual / Construction.pod
CommitLineData
daa0fd7d 1package Moose::Manual::Construction;
2
3# ABSTRACT: Object construction (and destruction) with Moose
9c397ba1 4
daa0fd7d 5__END__
9c397ba1 6
daa0fd7d 7=pod
9c397ba1 8
9=head1 WHERE'S THE CONSTRUCTOR?
10
f293b363 11B<Do not define a C<new()> method for your classes!>
9c397ba1 12
909103e1 13When you C<use Moose> in your class, your class becomes a subclass of
14L<Moose::Object>. The L<Moose::Object> provides a C<new()> method for your
15class. If you follow our recommendations in L<Moose::Manual::BestPractices>
16and make your class immutable, then you actually get a class-specific C<new()>
088f068f 17method "inlined" in your class.
9c397ba1 18
62225ecf 19=head1 OBJECT CONSTRUCTION AND ATTRIBUTES
20
9c397ba1 21The Moose-provided constructor accepts a hash or hash reference of
22named parameters matching your attributes (actually, matching their
23C<init_arg>s). This is just another way in which Moose keeps you from
24worrying I<how> classes are implemented. Simply define a class and
25you're ready to start creating objects!
26
5384dda8 27=head1 OBJECT CONSTRUCTION HOOKS
9c397ba1 28
088f068f 29Moose lets you hook into object construction. You can validate an
241108c4 30object's state, do logging, customize construction from parameters which
31do not match your attributes, or maybe allow non-hash(ref) constructor
088f068f 32arguments. You can do this by creating C<BUILD> and/or C<BUILDARGS>
33methods.
9c397ba1 34
088f068f 35If these methods exist in your class, Moose will arrange for them to
36be called as part of the object construction process.
9c397ba1 37
38=head2 BUILDARGS
39
088f068f 40The C<BUILDARGS> method is called as a class method I<before> an
41object is created. It will receive all of the arguments that were
909103e1 42passed to C<new()> I<as-is>, and is expected to return a hash
088f068f 43reference. This hash reference will be used to construct the object,
44so it should contain keys matching your attributes' names (well,
45C<init_arg>s).
9c397ba1 46
636f25f3 47One common use for C<BUILDARGS> is to accommodate a non-hash(ref)
9c397ba1 48calling style. For example, we might want to allow our Person class to
49be called with a single argument of a social security number, C<<
50Person->new($ssn) >>.
51
5384dda8 52Without a C<BUILDARGS> method, Moose will complain, because it expects
53a hash or hash reference. We can use the C<BUILDARGS> method to
636f25f3 54accommodate this calling style:
9c397ba1 55
c30bceb8 56 around BUILDARGS => sub {
909103e1 57 my $orig = shift;
9c397ba1 58 my $class = shift;
59
909103e1 60 if ( @_ == 1 && !ref $_[0] ) {
61 return $class->$orig( ssn => $_[0] );
9c397ba1 62 }
63 else {
c30bceb8 64 return $class->$orig(@_);
9c397ba1 65 }
c30bceb8 66 };
9c397ba1 67
909103e1 68Note the call to C<< $class->$orig >>. This will call the default C<BUILDARGS>
69in L<Moose::Object>. This method takes care of distinguishing between a hash
70reference and a plain hash for you.
9c397ba1 71
72=head2 BUILD
73
74The C<BUILD> method is called I<after> an object is created. There are
909103e1 75several reasons to use a C<BUILD> method. One of the most common is to
dab94063 76check that the object state is valid. While we can validate individual
77attributes through the use of types, we can't validate the state of a
78whole object that way.
9c397ba1 79
80 sub BUILD {
81 my $self = shift;
82
83 if ( $self->country_of_residence eq 'USA' ) {
84 die 'All US residents must have an SSN'
85 unless $self->has_ssn;
86 }
87 }
88
89Another use of a C<BUILD> method could be for logging or tracking
90object creation.
91
92 sub BUILD {
93 my $self = shift;
94
5384dda8 95 debug( 'Made a new person - SSN = ', $self->ssn, );
9c397ba1 96 }
97
241108c4 98
3eb64847 99The C<BUILD> method is called with the hash reference of the parameters passed
100to the constructor (after munging by C<BUILDARGS>). This gives you a chance to
101do something with parameters that do not represent object attributes.
241108c4 102
94650eb9 103 sub BUILD {
b4538f65 104 my $self = shift;
3eb64847 105 my $args = shift;
241108c4 106
3eb64847 107 $self->add_friend(
108 My::User->new(
109 user_id => $args->{user_id},
110 )
111 );
94650eb9 112 }
241108c4 113
d67ce58f 114=head3 BUILD and parent classes
9c397ba1 115
909103e1 116The interaction between multiple C<BUILD> methods in an inheritance hierarchy
117is different from normal Perl methods. B<You should never call C<<
118$self->SUPER::BUILD >>>, nor should you ever apply a method modifier to
119C<BUILD>.
9c397ba1 120
121Moose arranges to have all of the C<BUILD> methods in a hierarchy
122called when an object is constructed, I<from parents to
123children>. This might be surprising at first, because it reverses the
124normal order of method inheritance.
125
126The theory behind this is that C<BUILD> methods can only be used for
127increasing specialization of a class's constraints, so it makes sense
f293b363 128to call the least specific C<BUILD> method first. Also, this is how
129Perl 6 does it.
9c397ba1 130
5384dda8 131=head1 OBJECT DESTRUCTION
9c397ba1 132
133Moose provides a hook for object destruction with the C<DEMOLISH>
134method. As with C<BUILD>, you should never explicitly call C<<
135$self->SUPER::DEMOLISH >>. Moose will arrange for all of the
136C<DEMOLISH> methods in your hierarchy to be called, from most to least
137specific.
138
b288593e 139Each C<DEMOLISH> method is called with a single argument.
140
5384dda8 141In most cases, Perl's built-in garbage collection is sufficient, and
088f068f 142you won't need to provide a C<DEMOLISH> method.
5384dda8 143
b288593e 144=head2 Error Handling During Destruction
145
146The interaction of object destruction and Perl's global C<$@> and C<$?>
147variables can be very confusing.
148
149Moose always localizes C<$?> when an object is being destroyed. This means
150that if you explicitly call C<exit>, that exit code will be preserved even if
151an object's destructor makes a system call.
152
153Moose also preserves C<$@> against any C<eval> calls that may happen during
154object destruction. However, if an object's C<DEMOLISH> method actually dies,
155Moose explicitly rethrows that error.
156
157If you do not like this behavior, you will have to provide your own C<DESTROY>
158method and use that instead of the one provided by L<Moose::Object>. You can
159do this to preserve C<$@> I<and> capture any errors from object destruction by
160creating an error stack.
161
9c397ba1 162=cut