1Moose::Manual::ConstrucUtsieorn(C3o)ntributed Perl DocumMeonotsaet:i:oMnanual::Construction(3)
2
6 Moose::Manual::Construction - Object construction (and destruction)
7 with Moose
8
10 Do not define a "new()" method for your classes!
11 When you "use Moose" in your class, you will become a subclass of
13 Moose::Object, which provides a "new" method for you. If you follow our
14 recommendations in Moose::Manual::BestPractices and make your class
15 immutable, then you actually get a class-specific "new" method
16 "inlined" in your class.
17
19 The Moose-provided constructor accepts a hash or hash reference of
20 named parameters matching your attributes (actually, matching their
21 "init_arg"s). This is just another way in which Moose keeps you from
22 worrying how classes are implemented. Simply define a class and you're
23 ready to start creating objects!
24
26 Moose lets you hook into object construction. You can validate an
27 object's state, do logging, customize construction from parameters
28 which do not match your attributes, or maybe allow non-hash(ref)
29 constructor arguments. You can do this by creating "BUILD" and/or
30 "BUILDARGS" methods.
31 If these methods exist in your class, Moose will arrange for them to be
33 called as part of the object construction process.
34 BUILDARGS
36 The "BUILDARGS" method is called as a class method before an object is
37 created. It will receive all of the arguments that were passed to "new"
38 as-is, and is expected to return a hash reference. This hash reference
39 will be used to construct the object, so it should contain keys
40 matching your attributes' names (well, "init_arg"s).
41 One common use for "BUILDARGS" is to accommodate 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,
45 "Person->new($ssn)".
46 Without a "BUILDARGS" method, Moose will complain, because it expects a
48 hash or hash reference. We can use the "BUILDARGS" method to
49 accommodate this calling style:
50 around BUILDARGS => sub {
52 my $orig = shift;
53 my $class = shift;
54 if ( @_ == 1 && ! ref $_[0] ) {
56 return $class->$orig(ssn => $_[0]);
57 }
58 else {
59 return $class->$orig(@_);
60 }
61 };
62 Note the call to "$class->$orig". This will call the default
64 "BUILDARGS" in Moose::Object. This method handles distinguishing
65 between a hash reference and a plain hash for you.
66 BUILD
68 The "BUILD" method is called after an object is created. There are
69 several ways to use a "BUILD" method. One of the most common is to
70 check that the object state is valid. While we can validate individual
71 attributes through the use of types, we can't validate the state of a
72 whole object that way.
73 sub BUILD {
75 my $self = shift;
76 if ( $self->country_of_residence eq 'USA' ) {
78 die 'All US residents must have an SSN'
79 unless $self->has_ssn;
80 }
81 }
82 Another use of a "BUILD" method could be for logging or tracking object
84 creation.
85 sub BUILD {
87 my $self = shift;
88 debug( 'Made a new person - SSN = ', $self->ssn, );
90 }
91 The "BUILD" method is called with the hash reference of the parameters
93 passed to the constructor (after munging by "BUILDARGS"). This gives
94 you a chance to do something with parameters that do not represent
95 object attributes.
96 sub BUILD {
98 my $self = shift;
99 my $args = shift;
100 $self->add_friend(
102 My::User->new(
103 user_id => $args->{user_id},
104 )
105 );
106 }
107 BUILD and parent classes
109 The interaction between multiple "BUILD" methods in an inheritance
111 hierarchy is different from normal Perl methods. You should never call
112 "$self->SUPER::BUILD".
113 Moose arranges to have all of the "BUILD" methods in a hierarchy called
115 when an object is constructed, from parents to children. This might be
116 surprising at first, because it reverses the normal order of method
117 inheritance.
118 The theory behind this is that "BUILD" methods can only be used for
120 increasing specialization of a class's constraints, so it makes sense
121 to call the least specific "BUILD" method first. Also, this is how Perl
122 6 does it.
123
125 Moose provides a hook for object destruction with the "DEMOLISH"
126 method. As with "BUILD", you should never explicitly call
127 "$self->SUPER::DEMOLISH". Moose will arrange for all of the "DEMOLISH"
128 methods in your hierarchy to be called, from most to least specific.
129 Each "DEMOLISH" method is called with a single argument.
131 In most cases, Perl's built-in garbage collection is sufficient, and
133 you won't need to provide a "DEMOLISH" method.
134 Error Handling During Destruction
136 The interaction of object destruction and Perl's global $@ and $?
137 variables can be very confusing.
138 Moose always localizes $? when an object is being destroyed. This means
140 that if you explicitly call "exit", that exit code will be preserved
141 even if an object's destructor makes a system call.
142 Moose also preserves $@ against any "eval" calls that may happen during
144 object destruction. However, if an object's "DEMOLISH" method actually
145 dies, Moose explicitly rethrows that error.
146 If you do not like this behavior, you will have to provide your own
148 "DESTROY" method and use that instead of the one provided by
149 Moose::Object. You can do this to preserve $@ and capture any errors
150 from object destruction by creating an error stack.
151
153 Dave Rolsky <autarch@urth.org>
154
156 Copyright 2009 by Infinity Interactive, Inc.
157 <http://www.iinteractive.com>
159 This library is free software; you can redistribute it and/or modify it
161 under the same terms as Perl itself.
162perl v5.12.2 2010-08-21 Moose::Manual::Construction(3)