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 |
28 | object's state, do logging, or maybe allow non-hash(ref) constructor |
29 | arguments. You can do this by creating C<BUILD> and/or C<BUILDARGS> |
30 | methods. |
9c397ba1 |
31 | |
088f068f |
32 | If these methods exist in your class, Moose will arrange for them to |
33 | be called as part of the object construction process. |
9c397ba1 |
34 | |
35 | =head2 BUILDARGS |
36 | |
088f068f |
37 | The C<BUILDARGS> method is called as a class method I<before> an |
38 | object is created. It will receive all of the arguments that were |
39 | passed to C<new> I<as-is>, and is expected to return a hash |
40 | reference. This hash reference will be used to construct the object, |
41 | so it should contain keys matching your attributes' names (well, |
42 | C<init_arg>s). |
9c397ba1 |
43 | |
636f25f3 |
44 | One common use for C<BUILDARGS> is to accommodate a non-hash(ref) |
9c397ba1 |
45 | calling style. For example, we might want to allow our Person class to |
46 | be called with a single argument of a social security number, C<< |
47 | Person->new($ssn) >>. |
48 | |
5384dda8 |
49 | Without a C<BUILDARGS> method, Moose will complain, because it expects |
50 | a hash or hash reference. We can use the C<BUILDARGS> method to |
636f25f3 |
51 | accommodate this calling style: |
9c397ba1 |
52 | |
c30bceb8 |
53 | around BUILDARGS => sub { |
54 | my $orig = shift; |
9c397ba1 |
55 | my $class = shift; |
56 | |
57 | if ( @_ == 1 && ! ref $_[0] ) { |
c30bceb8 |
58 | return $class->$orig(ssn => $_[0]); |
9c397ba1 |
59 | } |
60 | else { |
c30bceb8 |
61 | return $class->$orig(@_); |
9c397ba1 |
62 | } |
c30bceb8 |
63 | }; |
9c397ba1 |
64 | |
c30bceb8 |
65 | Note the call to C<< $class->$orig >>. This will call the default |
0c39debe |
66 | C<BUILDARGS> in L<Moose::Object>. This method handles distinguishing |
088f068f |
67 | between a hash reference and a plain hash for you. |
9c397ba1 |
68 | |
69 | =head2 BUILD |
70 | |
71 | The C<BUILD> method is called I<after> an object is created. There are |
dab94063 |
72 | several ways to use a C<BUILD> method. One of the most common is to |
73 | check that the object state is valid. While we can validate individual |
74 | attributes through the use of types, we can't validate the state of a |
75 | whole object that way. |
9c397ba1 |
76 | |
77 | sub BUILD { |
78 | my $self = shift; |
79 | |
80 | if ( $self->country_of_residence eq 'USA' ) { |
81 | die 'All US residents must have an SSN' |
82 | unless $self->has_ssn; |
83 | } |
84 | } |
85 | |
86 | Another use of a C<BUILD> method could be for logging or tracking |
87 | object creation. |
88 | |
89 | sub BUILD { |
90 | my $self = shift; |
91 | |
5384dda8 |
92 | debug( 'Made a new person - SSN = ', $self->ssn, ); |
9c397ba1 |
93 | } |
94 | |
f882492b |
95 | Note that while it is not shown here, the C<BUILD> method receives |
96 | not only the created object, but also a hashref of the original |
97 | arguments passed to new (or the results of your C<BUILDARGS>, |
98 | if you have overridden the default C<BUILDARGS>.) This can be |
99 | useful if you need to venture beyond what the default |
100 | initialization behavior and coercions can accomplish. |
101 | |
d67ce58f |
102 | =head3 BUILD and parent classes |
9c397ba1 |
103 | |
104 | The interaction between multiple C<BUILD> methods in an inheritance |
105 | hierarchy is different from normal Perl methods. B<You should never |
106 | call C<< $self->SUPER::BUILD >>.> |
107 | |
108 | Moose arranges to have all of the C<BUILD> methods in a hierarchy |
109 | called when an object is constructed, I<from parents to |
110 | children>. This might be surprising at first, because it reverses the |
111 | normal order of method inheritance. |
112 | |
113 | The theory behind this is that C<BUILD> methods can only be used for |
114 | increasing specialization of a class's constraints, so it makes sense |
f293b363 |
115 | to call the least specific C<BUILD> method first. Also, this is how |
116 | Perl 6 does it. |
9c397ba1 |
117 | |
5384dda8 |
118 | =head1 OBJECT DESTRUCTION |
9c397ba1 |
119 | |
120 | Moose provides a hook for object destruction with the C<DEMOLISH> |
121 | method. As with C<BUILD>, you should never explicitly call C<< |
122 | $self->SUPER::DEMOLISH >>. Moose will arrange for all of the |
123 | C<DEMOLISH> methods in your hierarchy to be called, from most to least |
124 | specific. |
125 | |
b288593e |
126 | Each C<DEMOLISH> method is called with a single argument. |
127 | |
5384dda8 |
128 | In most cases, Perl's built-in garbage collection is sufficient, and |
088f068f |
129 | you won't need to provide a C<DEMOLISH> method. |
5384dda8 |
130 | |
b288593e |
131 | =head2 Error Handling During Destruction |
132 | |
133 | The interaction of object destruction and Perl's global C<$@> and C<$?> |
134 | variables can be very confusing. |
135 | |
136 | Moose always localizes C<$?> when an object is being destroyed. This means |
137 | that if you explicitly call C<exit>, that exit code will be preserved even if |
138 | an object's destructor makes a system call. |
139 | |
140 | Moose also preserves C<$@> against any C<eval> calls that may happen during |
141 | object destruction. However, if an object's C<DEMOLISH> method actually dies, |
142 | Moose explicitly rethrows that error. |
143 | |
144 | If you do not like this behavior, you will have to provide your own C<DESTROY> |
145 | method and use that instead of the one provided by L<Moose::Object>. You can |
146 | do this to preserve C<$@> I<and> capture any errors from object destruction by |
147 | creating an error stack. |
148 | |
9c397ba1 |
149 | =head1 AUTHOR |
150 | |
151 | Dave Rolsky E<lt>autarch@urth.orgE<gt> |
152 | |
153 | =head1 COPYRIGHT AND LICENSE |
154 | |
2840a3b2 |
155 | Copyright 2009 by Infinity Interactive, Inc. |
9c397ba1 |
156 | |
157 | L<http://www.iinteractive.com> |
158 | |
159 | This library is free software; you can redistribute it and/or modify |
160 | it under the same terms as Perl itself. |
161 | |
162 | =cut |