Commit | Line | Data |
9c397ba1 |
1 | =pod |
2 | |
3 | =head1 NAME |
4 | |
5 | Moose::Manual::Classes - Object construction (and destruction) with Moose |
6 | |
7 | =head1 WHERE'S THE CONSTRUCTOR? |
8 | |
5384dda8 |
9 | B<You do not need to 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 |
12 | C<Moose::Object>, which provides a C<new> method for you. And 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> |
15 | method genreated in your class. |
9c397ba1 |
16 | |
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! |
22 | |
5384dda8 |
23 | =head1 OBJECT CONSTRUCTION HOOKS |
9c397ba1 |
24 | |
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. |
29 | |
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. |
32 | |
33 | =head2 BUILDARGS |
34 | |
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). |
41 | |
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<< |
45 | Person->new($ssn) >>. |
46 | |
5384dda8 |
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: |
9c397ba1 |
50 | |
51 | sub BUILDARGS { |
52 | my $class = shift; |
53 | |
54 | if ( @_ == 1 && ! ref $_[0] ) { |
55 | return { ssn => $_[0] }; |
56 | } |
57 | else { |
58 | return $class->SUPER::BUILDARGS(@_); |
59 | } |
60 | } |
61 | |
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. |
65 | |
66 | =head2 BUILD |
67 | |
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. |
73 | |
74 | sub BUILD { |
75 | my $self = shift; |
76 | |
77 | if ( $self->country_of_residence eq 'USA' ) { |
78 | die 'All US residents must have an SSN' |
79 | unless $self->has_ssn; |
80 | } |
81 | } |
82 | |
83 | Another use of a C<BUILD> method could be for logging or tracking |
84 | object creation. |
85 | |
86 | sub BUILD { |
87 | my $self = shift; |
88 | |
5384dda8 |
89 | debug( 'Made a new person - SSN = ', $self->ssn, ); |
9c397ba1 |
90 | } |
91 | |
92 | =head3 BUILD and Parent Classes |
93 | |
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 >>.> |
97 | |
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. |
102 | |
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). |
106 | |
5384dda8 |
107 | =head1 OBJECT DESTRUCTION |
9c397ba1 |
108 | |
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 |
113 | specific. |
114 | |
5384dda8 |
115 | In most cases, Perl's built-in garbage collection is sufficient, and |
116 | you won't need ot provide a C<DEMOLISH> method. |
117 | |
9c397ba1 |
118 | =head1 AUTHOR |
119 | |
120 | Dave Rolsky E<lt>autarch@urth.orgE<gt> |
121 | |
122 | =head1 COPYRIGHT AND LICENSE |
123 | |
124 | Copyright 2008 by Infinity Interactive, Inc. |
125 | |
126 | L<http://www.iinteractive.com> |
127 | |
128 | This library is free software; you can redistribute it and/or modify |
129 | it under the same terms as Perl itself. |
130 | |
131 | =cut |