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 version 2.2015
11
13 Do not define a "new()" method for your classes!
14 When you "use Moose" in your class, your class becomes a subclass of
16 Moose::Object. The Moose::Object provides a "new()" method for your
17 class. If you follow our recommendations in
18 Moose::Manual::BestPractices and make your class immutable, then you
19 actually get a class-specific "new()" method "inlined" in your class.
20
22 The Moose-provided constructor accepts a hash or hash reference of
23 named parameters matching your attributes (actually, matching their
24 "init_arg"s). This is just another way in which Moose keeps you from
25 worrying how classes are implemented. Simply define a class and you're
26 ready to start creating objects!
27
29 Moose lets you hook into object construction. You can validate an
30 object's state, do logging, customize construction from parameters
31 which do not match your attributes, or maybe allow non-hash(ref)
32 constructor arguments. You can do this by creating "BUILD" and/or
33 "BUILDARGS" methods.
34 If these methods exist in your class, Moose will arrange for them to be
36 called as part of the object construction process.
37 BUILDARGS
39 The "BUILDARGS" method is called as a class method before an object is
40 created. It will receive all of the arguments that were passed to
41 "new()" as-is, and is expected to return a hash reference. This hash
42 reference will be used to construct the object, so it should contain
43 keys matching your attributes' names (well, "init_arg"s).
44 One common use for "BUILDARGS" is to accommodate a non-hash(ref)
46 calling style. For example, we might want to allow our Person class to
47 be called with a single argument of a social security number,
48 "Person->new($ssn)".
49 Without a "BUILDARGS" method, Moose will complain, because it expects a
51 hash or hash reference. We can use the "BUILDARGS" method to
52 accommodate this calling style:
53 around BUILDARGS => sub {
55 my $orig = shift;
56 my $class = shift;
57 if ( @_ == 1 && !ref $_[0] ) {
59 return $class->$orig( ssn => $_[0] );
60 }
61 else {
62 return $class->$orig(@_);
63 }
64 };
65 Note the call to "$class->$orig". This will call the default
67 "BUILDARGS" in Moose::Object. This method takes care of distinguishing
68 between a hash reference and a plain hash for you.
69 BUILD
71 The "BUILD" method is called after an object is created. There are
72 several reasons to use a "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.
76 sub BUILD {
78 my $self = shift;
79 if ( $self->country_of_residence eq 'USA' ) {
81 die 'All US residents must have an SSN'
82 unless $self->has_ssn;
83 }
84 }
85 Another use of a "BUILD" method could be for logging or tracking object
87 creation.
88 sub BUILD {
90 my $self = shift;
91 debug( 'Made a new person - SSN = ', $self->ssn, );
93 }
94 The "BUILD" method is called with the hash reference of the parameters
96 passed to the constructor (after munging by "BUILDARGS"). This gives
97 you a chance to do something with parameters that do not represent
98 object attributes.
99 sub BUILD {
101 my $self = shift;
102 my $args = shift;
103 $self->add_friend(
105 My::User->new(
106 user_id => $args->{user_id},
107 )
108 );
109 }
110 BUILD and parent classes
112 The interaction between multiple "BUILD" methods in an inheritance
114 hierarchy is different from normal Perl methods. You should never call
115 "$self->SUPER::BUILD", nor should you ever apply a method modifier to
116 "BUILD". Roles are an exception to this rule, though: it's completely
117 acceptable to apply a method modifier to "BUILD" in a role; you can
118 even provide an empty "BUILD" subroutine in a role so the role is
119 applicable even to classes without their own "BUILD".
120 Moose arranges to have all of the "BUILD" methods in a hierarchy called
122 when an object is constructed, from parents to children. This might be
123 surprising at first, because it reverses the normal order of method
124 inheritance.
125 The theory behind this is that "BUILD" methods can only be used for
127 increasing specialization of a class's constraints, so it makes sense
128 to call the least specific "BUILD" method first. Also, this is how Perl
129 6 does it.
130
132 Moose provides a hook for object destruction with the "DEMOLISH"
133 method. As with "BUILD", you should never explicitly call
134 "$self->SUPER::DEMOLISH". Moose will arrange for all of the "DEMOLISH"
135 methods in your hierarchy to be called, from most to least specific.
136 Each "DEMOLISH" method is called with a single argument. This is a
138 boolean value indicating whether or not this method was called as part
139 of the global destruction process (when the Perl interpreter exits).
140 In most cases, Perl's built-in garbage collection is sufficient, and
142 you won't need to provide a "DEMOLISH" method.
143 Error Handling During Destruction
145 The interaction of object destruction and Perl's global $@ and $?
146 variables can be very confusing.
147 Moose always localizes $? when an object is being destroyed. This means
149 that if you explicitly call "exit", that exit code will be preserved
150 even if an object's destructor makes a system call.
151 Moose also preserves $@ against any "eval" calls that may happen during
153 object destruction. However, if an object's "DEMOLISH" method actually
154 dies, Moose explicitly rethrows that error.
155 If you do not like this behavior, you will have to provide your own
157 "DESTROY" method and use that instead of the one provided by
158 Moose::Object. You can do this to preserve $@ and capture any errors
159 from object destruction by creating an error stack.
160
162 • Stevan Little <stevan@cpan.org>
163 • Dave Rolsky <autarch@urth.org>
165 • Jesse Luehrs <doy@cpan.org>
167 • Shawn M Moore <sartak@cpan.org>
169 • יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
171 • Karen Etheridge <ether@cpan.org>
173 • Florian Ragwitz <rafl@debian.org>
175 • Hans Dieter Pearcey <hdp@cpan.org>
177 • Chris Prather <chris@prather.org>
179 • Matt S Trout <mstrout@cpan.org>
181
183 This software is copyright (c) 2006 by Infinity Interactive, Inc.
184 This is free software; you can redistribute it and/or modify it under
186 the same terms as the Perl 5 programming language system itself.
187perl v5.34.0 2021-07-22 Moose::Manual::Construction(3)