5 Moose::Manual::Attribute - Moose's Method Modifiers
7 =head1 WHAT IS A METHOD MODIFIER?
9 Moose provides a feature called "method modifiers". Another word for
10 this feature might be "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 about roles.
70 Modifiers really are at their most useful in roles, so some of the
71 examples below are a bit artificial. They're intended to give you an
72 idea of how modifiers work, but may not be the most natural usages.
74 =head1 BEFORE, AFTER, AND AROUND
76 Method modifiers can also be used to add behavior to a method that
77 Moose 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 pre-checking 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 fit well into
102 Similarly, an after modifier could be used for logging an action that
105 Note that the return values of both before and after modifiers are
108 An around modifier is a bit more powerful than either a before or
109 after modifier. First, it is easy to modify the arguments being passed
110 onto the original method in an around modifier. Second, you can decide
111 to simply not call the original method at all, unlike with other
112 modifiers. Finally, you can modify the return value with an around
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 =head1 INNER AND AUGMENT
134 Augment and inner are two halves of the same feature. The augment
135 modifier provides a sort of inverted subclassing. You provide part of
136 the implementation in a superclass, and then document that subclasses
137 are expected to provide the rest.
139 The superclass calls C<inner()>, which then calls the C<augment>
140 modifier in the subclass:
149 my $xml = "<document>\n";
151 $xml .= "</document>\n";
156 Using C<inner()> in this method makes it possible for one or more
157 subclasses to then augment this method with their own specific
166 augment 'as_xml' => sub {
169 my $xml = "<report>\n";
171 $xml .= "</report>\n";
176 When we call C<as_xml> on a Report object, we get something like this:
183 But we also called C<inner()> in C<Report>, so we can continue
184 subclassing and adding more content inside the document:
186 package Report::IncomeAndExpenses;
192 augment 'as_xml' => sub {
195 my $xml = '<income>' . $self->income . '</income>';
197 my $xml = '<expenses>' . $self->expenses . '</expenses>';
200 $xml .= inner() || q{};
205 Now our report has some content:
210 <expenses>$8</expenses>
214 What makes this combination of C<augment> and C<inner()> special is
215 that it allows us to have methods which are called from I<parent
216 (least specific) to child (most specific). This inverts the normal
217 order, where the child's method is called first, and it in turn will
218 call C<< $self->SUPER::method >> to call the parent.
220 Note that in C<Report::IncomeAndExpenses> we call C<inner()> again. If
221 the object is an instance of C<Report::IncomeAndExpenses> then this
222 call is a no-op, and just returns false.
224 =head1 OVERRIDE AND SUPER
226 Finally, Moose provides some simple sugar for Perl's built-in method
227 overriding scheme. If you want to override a method from a parent
228 class, you can do this with C<override>:
236 has 'job_title' => ( is => 'rw' );
238 override 'display_name' => sub {
241 return super() . q{, } . $self->title();
244 The call to C<super()> is almost the same as calling C<<
245 $self->SUPER::display_name >>. The difference is that the arguments
246 passed to the superclass's method will always be the same as the ones
247 passed to the method modifier, and cannot be changed.
249 All arguments passed to C<super()> are ignored, as are any changes
250 made to C<@_> before C<super()> is called.
254 Because all of these method modifiers are implemented as Perl
255 functions, you must always end the modifier declaration with a
258 after 'foo' => sub { };
262 Dave Rolsky E<lt>autarch@urth.orgE<gt>
264 =head1 COPYRIGHT AND LICENSE
266 Copyright 2008 by Infinity Interactive, Inc.
268 L<http://www.iinteractive.com>
270 This library is free software; you can redistribute it and/or modify
271 it under the same terms as Perl itself.