1Moose::Manual::MethodMoUdsiefrieCrosn(t3r)ibuted Perl DoMcouomseen:t:aMtainounal::MethodModifiers(3)
2
6 Moose::Manual::MethodModifiers - Moose's method modifiers
7
9 Moose provides a feature called "method modifiers". You can also think
10 of these as "hooks" or "advice".
11 It's probably easiest to understand this feature with a few examples:
13 package Example;
15 use Moose;
17 sub foo {
19 print "foo\n";
20 }
21 before 'foo' => sub { print "about to call foo\n"; };
23 after 'foo' => sub { print "just called foo\n"; };
24 around 'foo' => sub {
26 my $orig = shift;
27 my $self = shift;
28 print "I'm around foo\n";
30 $self->$orig(@_);
32 print "I'm still around foo\n";
34 };
35 Now if I call "Example->new->foo" I'll get the following output:
37 about to call foo
39 I'm around foo
40 foo
41 I'm still around foo
42 just called foo
43 You probably could have figured that out from the names "before",
45 "after", and "around".
46 Also, as you can see, the before modifiers come before around
48 modifiers, and after modifiers come last.
49 When there are multiple modifiers of the same type, the before and
51 around modifiers run from the last added to the first, and after
52 modifiers run from first added to last:
53 before 2
55 before 1
56 around 2
57 around 1
58 primary
59 around 1
60 around 2
61 after 1
62 after 2
63
65 Method modifiers have many uses. One very common use is in roles. This
66 lets roles alter the behavior of methods in the classes that use them.
67 See Moose::Manual::Roles for more information about roles.
68 Since modifiers are mostly useful in roles, some of the examples below
70 are a bit artificial. They're intended to give you an idea of how
71 modifiers work, but may not be the most natural usage.
72
74 Method modifiers can be used to add behavior to a method that Moose
75 generates for you, such as an attribute accessor:
76 has 'size' => ( is => 'rw' );
78 before 'size' => sub {
80 my $self = shift;
81 if (@_) {
83 Carp::cluck('Someone is setting size');
84 }
85 };
86 Another use for the before modifier would be to do some sort of
88 prechecking on a method call. For example:
89 before 'size' => sub {
91 my $self = shift;
92 die 'Cannot set size while the person is growing'
94 if @_ && $self->is_growing;
95 };
96 This lets us implement logical checks that don't make sense as type
98 constraints. In particular, they're useful for defining logical rules
99 about an object's state changes.
100 Similarly, an after modifier could be used for logging an action that
102 was taken.
103 Note that the return values of both before and after modifiers are
105 ignored.
106 An around modifier is a bit more powerful than either a before or after
108 modifier. It can modify the arguments being passed to the original
109 method, and you can even decide to simply not call the original method
110 at all. You can also modify the return value with an around modifier.
111 An around modifier receives the original method as its first argument,
113 then the object, and finally any arguments passed to the method.
114 around 'size' => sub {
116 my $orig = shift;
117 my $self = shift;
118 return $self->$orig()
120 unless @_;
121 my $size = shift;
123 $size = $size / 2
124 if $self->likes_small_things();
125 return $self->$orig($size);
127 };
128 "before", "after", and "around" can also modify multiple methods at
130 once. The simplest example of this is passing them as a list:
131 before qw(foo bar baz) => sub {
133 warn "something is being called!";
134 };
135 This will add a "before" modifier to each of the "foo", "bar", and
137 "baz" methods in the current class, just as though a separate call to
138 "before" was made for each of them. The list can be passed either as a
139 bare list, or as an arrayref. Note that the name of the function being
140 modified isn't passed in in any way; this syntax is only intended for
141 cases where the function being modified doesn't actually matter. If the
142 function name does matter, something like:
143 for my $func (qw(foo bar baz)) {
145 before $func => sub {
146 warn "$func was called!";
147 };
148 }
149 would be more appropriate.
151 In addition, you can specify a regular expression to indicate the
153 methods to wrap, like so:
154 after qr/^command_/ => sub {
156 warn "got a command";
157 };
158 This will match the regular expression against each method name
160 returned by "get_method_list" in Class::MOP::Class, and add a modifier
161 to each one that matches. The same caveats apply as above, regarding
162 not being given the name of the method being modified. Using regular
163 expressions to determine methods to wrap is quite a bit more powerful
164 than the previous alternatives, but it's also quite a bit more
165 dangerous. In particular, you should make sure to avoid wrapping
166 methods with a special meaning to Moose or Perl, such as "meta",
167 "BUILD", "DESTROY", "AUTOLOAD", etc., as this could cause unintended
168 (and hard to debug) problems.
169
171 Augment and inner are two halves of the same feature. The augment
172 modifier provides a sort of inverted subclassing. You provide part of
173 the implementation in a superclass, and then document that subclasses
174 are expected to provide the rest.
175 The superclass calls "inner()", which then calls the "augment" modifier
177 in the subclass:
178 package Document;
180 use Moose;
182 sub as_xml {
184 my $self = shift;
185 my $xml = "<document>\n";
187 $xml .= inner();
188 $xml .= "</document>\n";
189 return $xml;
191 }
192 Using "inner()" in this method makes it possible for one or more
194 subclasses to then augment this method with their own specific
195 implementation:
196 package Report;
198 use Moose;
200 extends 'Document';
202 augment 'as_xml' => sub {
204 my $self = shift;
205 my $xml = "<report>\n";
207 $xml .= inner();
208 $xml .= "</report>\n";
209 return $xml;
211 };
212 When we call "as_xml" on a Report object, we get something like this:
214 <document>
216 <report>
217 </report>
218 </document>
219 But we also called "inner()" in "Report", so we can continue
221 subclassing and adding more content inside the document:
222 package Report::IncomeAndExpenses;
224 use Moose;
226 extends 'Report';
228 augment 'as_xml' => sub {
230 my $self = shift;
231 my $xml = '<income>' . $self->income . '</income>';
233 $xml .= "\n";
234 $xml .= '<expenses>' . $self->expenses . '</expenses>';
235 $xml .= "\n";
236 $xml .= inner() || q{};
238 return $xml;
240 };
241 Now our report has some content:
243 <document>
245 <report>
246 <income>$10</income>
247 <expenses>$8</expenses>
248 </report>
249 </document>
250 What makes this combination of "augment" and "inner()" special is that
252 it allows us to have methods which are called from parent (least
253 specific) to child (most specific). This inverts the normal inheritance
254 pattern.
255 Note that in "Report::IncomeAndExpenses" we call "inner()" again. If
257 the object is an instance of "Report::IncomeAndExpenses" then this call
258 is a no-op, and just returns false.
259
261 Finally, Moose provides some simple sugar for Perl's built-in method
262 overriding scheme. If you want to override a method from a parent
263 class, you can do this with "override":
264 package Employee;
266 use Moose;
268 extends 'Person';
270 has 'job_title' => ( is => 'rw' );
272 override 'display_name' => sub {
274 my $self = shift;
275 return super() . q{, } . $self->title();
277 };
278 The call to "super()" is almost the same as calling
280 "$self->SUPER::display_name". The difference is that the arguments
281 passed to the superclass's method will always be the same as the ones
282 passed to the method modifier, and cannot be changed.
283 All arguments passed to "super()" are ignored, as are any changes made
285 to @_ before "super()" is called.
286
288 Because all of these method modifiers are implemented as Perl
289 functions, you must always end the modifier declaration with a semi-
290 colon:
291 after 'foo' => sub { };
293
295 Dave Rolsky <autarch@urth.org>
296
298 Copyright 2008-2009 by Infinity Interactive, Inc.
299 <http://www.iinteractive.com>
301 This library is free software; you can redistribute it and/or modify it
303 under the same terms as Perl itself.
304perl v5.12.2 2010-08-21 Moose::Manual::MethodModifiers(3)