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 |
088f068f |
12 | C<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 | |
44 | One common use for C<BUILDARGS> is to accomodate a non-hash(ref) |
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 |
51 | accomodate this calling style: |
9c397ba1 |
52 | |
53 | sub BUILDARGS { |
54 | my $class = shift; |
55 | |
56 | if ( @_ == 1 && ! ref $_[0] ) { |
57 | return { ssn => $_[0] }; |
58 | } |
59 | else { |
60 | return $class->SUPER::BUILDARGS(@_); |
61 | } |
62 | } |
63 | |
64 | Note the call to C<SUPER::BUILDARGS>. This will call the default |
65 | C<BUILDARGS> in C<Moose::Object>. This method handles distinguishing |
088f068f |
66 | between a hash reference and a plain hash for you. |
9c397ba1 |
67 | |
68 | =head2 BUILD |
69 | |
70 | The C<BUILD> method is called I<after> an object is created. There are |
088f068f |
71 | ways to use a C<BUILD> method. One of the most common is to check that |
72 | the object state is valid. While we can validate individual attributes |
73 | through the use of types, we can't validate the state of a whole |
74 | object that way. |
9c397ba1 |
75 | |
76 | sub BUILD { |
77 | my $self = shift; |
78 | |
79 | if ( $self->country_of_residence eq 'USA' ) { |
80 | die 'All US residents must have an SSN' |
81 | unless $self->has_ssn; |
82 | } |
83 | } |
84 | |
85 | Another use of a C<BUILD> method could be for logging or tracking |
86 | object creation. |
87 | |
88 | sub BUILD { |
89 | my $self = shift; |
90 | |
5384dda8 |
91 | debug( 'Made a new person - SSN = ', $self->ssn, ); |
9c397ba1 |
92 | } |
93 | |
94 | =head3 BUILD and Parent Classes |
95 | |
96 | The interaction between multiple C<BUILD> methods in an inheritance |
97 | hierarchy is different from normal Perl methods. B<You should never |
98 | call C<< $self->SUPER::BUILD >>.> |
99 | |
100 | Moose arranges to have all of the C<BUILD> methods in a hierarchy |
101 | called when an object is constructed, I<from parents to |
102 | children>. This might be surprising at first, because it reverses the |
103 | normal order of method inheritance. |
104 | |
105 | The theory behind this is that C<BUILD> methods can only be used for |
106 | increasing specialization of a class's constraints, so it makes sense |
107 | to call the least specific first (also, this is how Perl 6 does it). |
108 | |
5384dda8 |
109 | =head1 OBJECT DESTRUCTION |
9c397ba1 |
110 | |
111 | Moose provides a hook for object destruction with the C<DEMOLISH> |
112 | method. As with C<BUILD>, you should never explicitly call C<< |
113 | $self->SUPER::DEMOLISH >>. Moose will arrange for all of the |
114 | C<DEMOLISH> methods in your hierarchy to be called, from most to least |
115 | specific. |
116 | |
5384dda8 |
117 | In most cases, Perl's built-in garbage collection is sufficient, and |
088f068f |
118 | you won't need to provide a C<DEMOLISH> method. |
5384dda8 |
119 | |
9c397ba1 |
120 | =head1 AUTHOR |
121 | |
122 | Dave Rolsky E<lt>autarch@urth.orgE<gt> |
123 | |
124 | =head1 COPYRIGHT AND LICENSE |
125 | |
126 | Copyright 2008 by Infinity Interactive, Inc. |
127 | |
128 | L<http://www.iinteractive.com> |
129 | |
130 | This library is free software; you can redistribute it and/or modify |
131 | it under the same terms as Perl itself. |
132 | |
133 | =cut |