Fix a typo
[gitmo/Moose.git] / lib / Moose / Manual / Construction.pod
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
9 B<You do not need to define a C<new()> method for your classes!>
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. If you
13 follow our recommendations in L<Moose::Manual::BestPractices> and make
14 your class immutable, then you actually get a class-specific C<new>
15 method "inlined" in your class.
16
17 =head1 OBJECT CONSTRUCTION AND ATTRIBUTES
18
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
25 =head1 OBJECT CONSTRUCTION HOOKS
26
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.
31
32 If these methods exist in your class, Moose will arrange for them to
33 be called as part of the object construction process.
34
35 =head2 BUILDARGS
36
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).
43
44 One common use for C<BUILDARGS> is to accommodate 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
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 accommodate this calling style:
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
66 between a hash reference and a plain hash for you.
67
68 =head2 BUILD
69
70 The C<BUILD> method is called I<after> an object is created. There are
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.
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
91       debug( 'Made a new person - SSN = ', $self->ssn, );
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
109 =head1 OBJECT DESTRUCTION
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
117 In most cases, Perl's built-in garbage collection is sufficient, and
118 you won't need to provide a C<DEMOLISH> method.
119
120 =head1 AUTHOR
121
122 Dave Rolsky E<lt>autarch@urth.orgE<gt>
123
124 =head1 COPYRIGHT AND LICENSE
125
126 Copyright 2009 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