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