5 Moose::Manual::MethodModifiers - Moose's method modifiers
7 =head1 WHAT IS A METHOD MODIFIER?
9 Moose provides a feature called "method modifiers". You can also think
10 of these as "hooks" or "advice".
12 It's probably easiest to understand this feature with a few examples:
22 before 'foo' => sub { print "about to call foo\n"; };
23 after 'foo' => sub { print "just called foo\n"; };
29 print "I'm around foo\n";
33 print "I'm still around foo\n";
36 Now if I call C<< Example->new->foo >> I'll get the following output:
44 You probably could have figured that out from the names "before",
45 "after", and "around".
47 Also, as you can see, the before modifiers come before around
48 modifiers, and after modifiers come last.
50 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:
66 Method modifiers have many uses. One very common use is in roles. This
67 lets roles alter the behavior of methods in the classes that use
68 them. See L<Moose::Manual::Roles> for more information about roles.
70 Since modifiers are mostly useful in roles, some of the examples below
71 are a bit artificial. They're intended to give you an idea of how
72 modifiers work, but may not be the most natural usage.
74 =head1 BEFORE, AFTER, AND AROUND
76 Method modifiers can be used to add behavior to a method that Moose
77 generates for you, such as an attribute accessor:
79 has 'size' => ( is => 'rw' );
81 before 'size' => sub {
85 Carp::cluck('Someone is setting size');
89 Another use for the before modifier would be to do some sort of
90 prechecking on a method call. For example:
92 before 'size' => sub {
95 die 'Cannot set size while the person is growing'
96 if @_ && $self->is_growing;
99 This lets us implement logical checks that don't make sense as type
100 constraints. In particular, they're useful for defining logical rules
101 about an object's state changes.
103 Similarly, an after modifier could be used for logging an action that
106 Note that the return values of both before and after modifiers are
109 An around modifier is a bit more powerful than either a before or
110 after modifier. It can modify the arguments being passed to the
111 original method, and you can even decide to simply not call the
112 original method at all. You can also modify the return value with an
115 An around modifier receives the original method as its first argument,
116 I<then> the object, and finally any arguments passed to the method.
118 around 'size' => sub {
122 return $self->$orig()
127 if $self->likes_small_things();
129 return $self->$orig($size);
132 C<before>, C<after>, and C<around> can also modify multiple methods
133 at once. The simplest example of this is passing them as a list:
135 before qw(foo bar baz) => sub {
136 warn "something is being called!";
139 This will add a C<before> modifier to each of the C<foo>, C<bar>,
140 and C<baz> methods in the current class, just as though a separate
141 call to C<before> was made for each of them. The list can be passed
142 either as a bare list, or as an arrayref. Note that the name of the
143 function being modified isn't passed in in any way; this syntax is
144 only intended for cases where the function being modified doesn't
145 actually matter. If the function name does matter, something like:
147 for my $func (qw(foo bar baz)) {
148 before $func => sub {
149 warn "$func was called!";
153 would be more appropriate.
155 In addition, you can specify a regular expression to indicate the
156 methods to wrap, like so:
158 after qr/^command_/ => sub {
159 warn "got a command";
162 This will match the regular expression against each method name
163 returned by L<Class::MOP::Class/get_method_list>, and add a modifier
164 to each one that matches. The same caveats apply as above, regarding
165 not being given the name of the method being modified. Using regular
166 expressions to determine methods to wrap is quite a bit more powerful
167 than the previous alternatives, but it's also quite a bit more
168 dangerous. In particular, you should make sure to avoid wrapping
169 methods with a special meaning to Moose or Perl, such as C<meta>,
170 C<BUILD>, C<DESTROY>, C<AUTOLOAD>, etc., as this could cause
171 unintended (and hard to debug) problems.
173 =head1 INNER AND AUGMENT
175 Augment and inner are two halves of the same feature. The augment
176 modifier provides a sort of inverted subclassing. You provide part of
177 the implementation in a superclass, and then document that subclasses
178 are expected to provide the rest.
180 The superclass calls C<inner()>, which then calls the C<augment>
181 modifier in the subclass:
190 my $xml = "<document>\n";
192 $xml .= "</document>\n";
197 Using C<inner()> in this method makes it possible for one or more
198 subclasses to then augment this method with their own specific
207 augment 'as_xml' => sub {
210 my $xml = "<report>\n";
212 $xml .= "</report>\n";
217 When we call C<as_xml> on a Report object, we get something like this:
224 But we also called C<inner()> in C<Report>, so we can continue
225 subclassing and adding more content inside the document:
227 package Report::IncomeAndExpenses;
233 augment 'as_xml' => sub {
236 my $xml = '<income>' . $self->income . '</income>';
238 $xml .= '<expenses>' . $self->expenses . '</expenses>';
241 $xml .= inner() || q{};
246 Now our report has some content:
251 <expenses>$8</expenses>
255 What makes this combination of C<augment> and C<inner()> special is
256 that it allows us to have methods which are called from parent (least
257 specific) to child (most specific). This inverts the normal
260 Note that in C<Report::IncomeAndExpenses> we call C<inner()> again. If
261 the object is an instance of C<Report::IncomeAndExpenses> then this
262 call is a no-op, and just returns false.
264 =head1 OVERRIDE AND SUPER
266 Finally, Moose provides some simple sugar for Perl's built-in method
267 overriding scheme. If you want to override a method from a parent
268 class, you can do this with C<override>:
276 has 'job_title' => ( is => 'rw' );
278 override 'display_name' => sub {
281 return super() . q{, } . $self->title();
284 The call to C<super()> is almost the same as calling C<<
285 $self->SUPER::display_name >>. The difference is that the arguments
286 passed to the superclass's method will always be the same as the ones
287 passed to the method modifier, and cannot be changed.
289 All arguments passed to C<super()> are ignored, as are any changes
290 made to C<@_> before C<super()> is called.
294 Because all of these method modifiers are implemented as Perl
295 functions, you must always end the modifier declaration with a
298 after 'foo' => sub { };
302 Dave Rolsky E<lt>autarch@urth.orgE<gt>
304 =head1 COPYRIGHT AND LICENSE
306 Copyright 2008-2009 by Infinity Interactive, Inc.
308 L<http://www.iinteractive.com>
310 This library is free software; you can redistribute it and/or modify
311 it under the same terms as Perl itself.