1Moose::Manual::MethodMoUdsiefrieCrosn(t3r)ibuted Perl DoMcouomseen:t:aMtainounal::MethodModifiers(3)
2
6 Moose::Manual::MethodModifiers - Moose's method modifiers
7
9 version 2.2206
10
12 Moose provides a feature called "method modifiers". You can also think
13 of these as "hooks" or "advice".
14 It's probably easiest to understand this feature with a few examples:
16 package Example;
18 use Moose;
20 sub foo {
22 print " foo\n";
23 }
24 before 'foo' => sub { print "about to call foo\n"; };
26 after 'foo' => sub { print "just called foo\n"; };
27 around 'foo' => sub {
29 my $orig = shift;
30 my $self = shift;
31 print " I'm around foo\n";
33 $self->$orig(@_);
35 print " I'm still around foo\n";
37 };
38 Now if I call "Example->new->foo" I'll get the following output:
40 about to call foo
42 I'm around foo
43 foo
44 I'm still around foo
45 just called foo
46 You probably could have figured that out from the names "before",
48 "after", and "around".
49 Also, as you can see, the before modifiers come before around
51 modifiers, and after modifiers come last.
52 When there are multiple modifiers of the same type, the before and
54 around modifiers run from the last added to the first, and after
55 modifiers run from first added to last:
56 before 2
58 before 1
59 around 2
60 around 1
61 primary
62 around 1
63 around 2
64 after 1
65 after 2
66
68 Method modifiers have many uses. They are often used in roles to alter
69 the behavior of methods in the classes that consume the role. See
70 Moose::Manual::Roles for more information about roles.
71 Since modifiers are mostly useful in roles, some of the examples below
73 are a bit artificial. They're intended to give you an idea of how
74 modifiers work, but may not be the most natural usage.
75
77 Method modifiers can be used to add behavior to methods without
78 modifying the definition of those methods.
79 Before and after Modifiers
81 Method modifiers can be used to add behavior to a method that Moose
82 generates for you, such as an attribute accessor:
83 has 'size' => ( is => 'rw' );
85 before 'size' => sub {
87 my $self = shift;
88 if (@_) {
90 Carp::cluck('Someone is setting size');
91 }
92 };
93 Another use for the before modifier would be to do some sort of
95 prechecking on a method call. For example:
96 before 'size' => sub {
98 my $self = shift;
99 die 'Cannot set size while the person is growing'
101 if @_ && $self->is_growing;
102 };
103 This lets us implement logical checks that don't make sense as type
105 constraints. In particular, they're useful for defining logical rules
106 about an object's state changes.
107 Similarly, an after modifier could be used for logging an action that
109 was taken.
110 Note that the return values of both before and after modifiers are
112 ignored.
113 Around modifiers
115 An around modifier is more powerful than either a before or after
116 modifier. It can modify the arguments being passed to the original
117 method, and you can even decide to simply not call the original method
118 at all. You can also modify the return value with an around modifier.
119 An around modifier receives the original method as its first argument,
121 then the object, and finally any arguments passed to the method.
122 around 'size' => sub {
124 my $orig = shift;
125 my $self = shift;
126 return $self->$orig()
128 unless @_;
129 my $size = shift;
131 $size = $size / 2
132 if $self->likes_small_things();
133 return $self->$orig($size);
135 };
136 Wrapping multiple methods at once
138 "before", "after", and "around" can also modify multiple methods at
139 once. The simplest example of this is passing them as a list:
140 before [qw(foo bar baz)] => sub {
142 warn "something is being called!";
143 };
144 This will add a "before" modifier to each of the "foo", "bar", and
146 "baz" methods in the current class, just as though a separate call to
147 "before" was made for each of them. The list can be passed either as a
148 bare list, or as an arrayref. Note that the name of the function being
149 modified isn't passed in in any way; this syntax is only intended for
150 cases where the function being modified doesn't actually matter. If the
151 function name does matter, use something like this:
152 for my $func (qw(foo bar baz)) {
154 before $func => sub {
155 warn "$func was called!";
156 };
157 }
158 Using regular expressions to select methods to wrap
160 In addition, you can specify a regular expression to indicate the
161 methods to wrap, like so:
162 after qr/^command_/ => sub {
164 warn "got a command";
165 };
166 This will match the regular expression against each method name
168 returned by "get_method_list" in Class::MOP::Class, and add a modifier
169 to each one that matches. The same caveats apply as above.
170 Using regular expressions to determine methods to wrap is quite a bit
172 more powerful than the previous alternatives, but it's also quite a bit
173 more dangerous. Bear in mind that if your regular expression matches
174 certain Perl and Moose reserved method names with a special meaning to
175 Moose or Perl, such as "meta", "new", "BUILD", "DESTROY", "AUTOLOAD",
176 etc, this could cause unintended (and hard to debug) problems and is
177 best avoided.
178 Execution order of method modifiers and inheritance
180 When both a superclass and an inheriting class have the same method
181 modifiers, the method modifiers of the inheriting class are wrapped
182 around the method modifiers of the superclass, as the following example
183 illustrates:
184 Here is the parent class:
186 package Superclass;
188 use Moose;
189 sub rant { printf " RANTING!\n" }
190 before 'rant' => sub { printf " In %s before\n", __PACKAGE__ };
191 after 'rant' => sub { printf " In %s after\n", __PACKAGE__ };
192 around 'rant' => sub {
193 my $orig = shift;
194 my $self = shift;
195 printf " In %s around before calling original\n", __PACKAGE__;
196 $self->$orig;
197 printf " In %s around after calling original\n", __PACKAGE__;
198 };
199 1;
200 And the child class:
202 package Subclass;
204 use Moose;
205 extends 'Superclass';
206 before 'rant' => sub { printf "In %s before\n", __PACKAGE__ };
207 after 'rant' => sub { printf "In %s after\n", __PACKAGE__ };
208 around 'rant' => sub {
209 my $orig = shift;
210 my $self = shift;
211 printf " In %s around before calling original\n", __PACKAGE__;
212 $self->$orig;
213 printf " In %s around after calling original\n", __PACKAGE__;
214 };
215 1;
216 And here's the output when we call the wrapped method ("Child->rant"):
218 % perl -MSubclass -e 'Subclass->new->rant'
220 In Subclass before
222 In Subclass around before calling original
223 In Superclass before
224 In Superclass around before calling original
225 RANTING!
226 In Superclass around after calling original
227 In Superclass after
228 In Subclass around after calling original
229 In Subclass after
230
232 Augment and inner are two halves of the same feature. The augment
233 modifier provides a sort of inverted subclassing. You provide part of
234 the implementation in a superclass, and then document that subclasses
235 are expected to provide the rest.
236 The superclass calls inner(), which then calls the "augment" modifier
238 in the subclass:
239 package Document;
241 use Moose;
243 sub as_xml {
245 my $self = shift;
246 my $xml = "<document>\n";
248 $xml .= inner();
249 $xml .= "</document>\n";
250 return $xml;
252 }
253 Using inner() in this method makes it possible for one or more
255 subclasses to then augment this method with their own specific
256 implementation:
257 package Report;
259 use Moose;
261 extends 'Document';
263 augment 'as_xml' => sub {
265 my $self = shift;
266 my $xml = " <report>\n";
268 $xml .= inner();
269 $xml .= " </report>\n";
270 return $xml;
272 };
273 When we call "as_xml" on a Report object, we get something like this:
275 <document>
277 <report>
278 </report>
279 </document>
280 But we also called inner() in "Report", so we can continue subclassing
282 and adding more content inside the document:
283 package Report::IncomeAndExpenses;
285 use Moose;
287 extends 'Report';
289 augment 'as_xml' => sub {
291 my $self = shift;
292 my $xml = ' <income>' . $self->income . '</income>';
294 $xml .= "\n";
295 $xml .= ' <expenses>' . $self->expenses . '</expenses>';
296 $xml .= "\n";
297 $xml .= inner() || q{};
299 return $xml;
301 };
302 Now our report has some content:
304 <document>
306 <report>
307 <income>$10</income>
308 <expenses>$8</expenses>
309 </report>
310 </document>
311 What makes this combination of "augment" and inner() special is that it
313 allows us to have methods which are called from parent (least specific)
314 to child (most specific). This inverts the normal inheritance pattern.
315 Note that in "Report::IncomeAndExpenses" we call inner() again. If the
317 object is an instance of "Report::IncomeAndExpenses" then this call is
318 a no-op, and just returns false. It's a good idea to always call
319 inner() to allow for future subclassing.
320
322 Finally, Moose provides some simple sugar for Perl's built-in method
323 overriding scheme. If you want to override a method from a parent
324 class, you can do this with "override":
325 package Employee;
327 use Moose;
329 extends 'Person';
331 has 'job_title' => ( is => 'rw' );
333 override 'display_name' => sub {
335 my $self = shift;
336 return super() . q{, } . $self->job_title();
338 };
339 The call to super() is almost the same as calling
341 "$self->SUPER::display_name". The difference is that the arguments
342 passed to the superclass's method will always be the same as the ones
343 passed to the method modifier, and cannot be changed.
344 All arguments passed to super() are ignored, as are any changes made to
346 @_ before super() is called.
347
349 Because all of these method modifiers are implemented as Perl
350 functions, you must always end the modifier declaration with a semi-
351 colon:
352 after 'foo' => sub { };
354
356 An exception thrown in a "before" modifier will prevent the method it
357 modifies from being called at all. An exception in an "around" modifier
358 may prevent the modified method from being called, depending on how the
359 "around" modifier is structured. An exception in an "after" modifier
360 obviously cannot prevent the method it wraps from being called.
361 Both "override" and "augment" are similar to "around" in that they can
363 decide whether or not to call the method they modify before or after
364 throwing an exception.
365 From the caller's perspective, an exception in a method modifier will
367 look like the method it called threw an exception. However, method
368 modifiers are just standard Perl subroutines. This means that they end
369 up on the stack in stack traces as an additional frame.
370
372 These method modification features do not work well with multiple
373 inheritance, due to how method resolution is performed in Perl.
374 Experiment with a test program to ensure your class hierarchy works as
375 expected, or more preferably, don't use multiple inheritance (roles can
376 help with this)!
377
379 • Stevan Little <stevan@cpan.org>
380 • Dave Rolsky <autarch@urth.org>
382 • Jesse Luehrs <doy@cpan.org>
384 • Shawn M Moore <sartak@cpan.org>
386 • יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
388 • Karen Etheridge <ether@cpan.org>
390 • Florian Ragwitz <rafl@debian.org>
392 • Hans Dieter Pearcey <hdp@cpan.org>
394 • Chris Prather <chris@prather.org>
396 • Matt S Trout <mstrout@cpan.org>
398
400 This software is copyright (c) 2006 by Infinity Interactive, Inc.
401 This is free software; you can redistribute it and/or modify it under
403 the same terms as the Perl 5 programming language system itself.
404perl v5.38.0 2023-07-23 Moose::Manual::MethodModifiers(3)