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