It's probably easiest to understand this feature with a few examples:
package Example;
use Moose;
sub foo {
print " foo\n";
}
before 'foo' => sub { print "about to call foo\n"; };
after 'foo' => sub { print "just called foo\n"; };
around 'foo' => sub {
my $orig = shift;
my $self = shift;
print " I'm around foo\n";
$self->$orig(@_);
print " I'm still around foo\n";
};
Now if I call "Example->new->foo" I'll get the following output:
about to call foo
I'm around foo
foo
I'm still around foo
just called foo
You probably could have figured that out from the names ``before'', ``after'', and ``around''.
Also, as you can see, the before modifiers come before around modifiers, and after modifiers come last.
When there are multiple modifiers of the same type, the before and around modifiers run from the last added to the first, and after modifiers run from first added to last:
before 2
before 1
around 2
around 1
primary
around 1
around 2
after 1
after 2
Since modifiers are mostly useful in roles, some of the examples below are a bit artificial. They're intended to give you an idea of how modifiers work, but may not be the most natural usage.
has 'size' => ( is => 'rw' );
before 'size' => sub {
my $self = shift;
if (@_) {
Carp::cluck('Someone is setting size');
}
};
Another use for the before modifier would be to do some sort of prechecking on a method call. For example:
before 'size' => sub {
my $self = shift;
die 'Cannot set size while the person is growing'
if @_ && $self->is_growing;
};
This lets us implement logical checks that don't make sense as type constraints. In particular, they're useful for defining logical rules about an object's state changes.
Similarly, an after modifier could be used for logging an action that was taken.
Note that the return values of both before and after modifiers are ignored.
An around modifier receives the original method as its first argument, then the object, and finally any arguments passed to the method.
around 'size' => sub {
my $orig = shift;
my $self = shift;
return $self->$orig()
unless @_;
my $size = shift;
$size = $size / 2
if $self->likes_small_things();
return $self->$orig($size);
};
before [qw(foo bar baz)] => sub {
warn "something is being called!";
};
This will add a "before" modifier to each of the "foo", "bar", and "baz" methods in the current class, just as though a separate call to "before" was made for each of them. The list can be passed either as a bare list, or as an arrayref. Note that the name of the function being modified isn't passed in in any way; this syntax is only intended for cases where the function being modified doesn't actually matter. If the function name does matter, use something like this:
for my $func (qw(foo bar baz)) {
before $func => sub {
warn "$func was called!";
};
}
after qr/^command_/ => sub {
warn "got a command";
};
This will match the regular expression against each method name returned by ``get_method_list'' in Class::MOP::Class, and add a modifier to each one that matches. The same caveats apply as above.
Using regular expressions to determine methods to wrap is quite a bit more powerful than the previous alternatives, but it's also quite a bit more dangerous. Bear in mind that if your regular expression matches certain Perl and Moose reserved method names with a special meaning to Moose or Perl, such as "meta", "new", "BUILD", "DESTROY", "AUTOLOAD", etc, this could cause unintended (and hard to debug) problems and is best avoided.
Here is the parent class:
package Superclass;
use Moose;
sub rant { printf " RANTING!\n" }
before 'rant' => sub { printf " In %s before\n", __PACKAGE__ };
after 'rant' => sub { printf " In %s after\n", __PACKAGE__ };
around 'rant' => sub {
my $orig = shift;
my $self = shift;
printf " In %s around before calling original\n", __PACKAGE__;
$self->$orig;
printf " In %s around after calling original\n", __PACKAGE__;
};
1;
And the child class:
package Subclass;
use Moose;
extends 'Superclass';
before 'rant' => sub { printf "In %s before\n", __PACKAGE__ };
after 'rant' => sub { printf "In %s after\n", __PACKAGE__ };
around 'rant' => sub {
my $orig = shift;
my $self = shift;
printf " In %s around before calling original\n", __PACKAGE__;
$self->$orig;
printf " In %s around after calling original\n", __PACKAGE__;
};
1;
And here's the output when we call the wrapped method ("Child->rant"):
% perl -MSubclass -e 'Subclass->new->rant'
In Subclass before
In Subclass around before calling original
In Superclass before
In Superclass around before calling original
RANTING!
In Superclass around after calling original
In Superclass after
In Subclass around after calling original
In Subclass after
The superclass calls "inner()", which then calls the "augment" modifier in the subclass:
package Document;
use Moose;
sub as_xml {
my $self = shift;
my $xml = "<document>\n";
$xml .= inner();
$xml .= "</document>\n";
return $xml;
}
Using "inner()" in this method makes it possible for one or more subclasses to then augment this method with their own specific implementation:
package Report;
use Moose;
extends 'Document';
augment 'as_xml' => sub {
my $self = shift;
my $xml = " <report>\n";
$xml .= inner();
$xml .= " </report>\n";
return $xml;
};
When we call "as_xml" on a Report object, we get something like this:
<document>
<report>
</report>
</document>
But we also called "inner()" in "Report", so we can continue subclassing and adding more content inside the document:
package Report::IncomeAndExpenses;
use Moose;
extends 'Report';
augment 'as_xml' => sub {
my $self = shift;
my $xml = ' <income>' . $self->income . '</income>';
$xml .= "\n";
$xml .= ' <expenses>' . $self->expenses . '</expenses>';
$xml .= "\n";
$xml .= inner() || q{};
return $xml;
};
Now our report has some content:
<document>
<report>
<income>$10</income>
<expenses>$8</expenses>
</report>
</document>
What makes this combination of "augment" and "inner()" special is that it allows us to have methods which are called from parent (least specific) to child (most specific). This inverts the normal inheritance pattern.
Note that in "Report::IncomeAndExpenses" we call "inner()" again. If the object is an instance of "Report::IncomeAndExpenses" then this call is a no-op, and just returns false. It's a good idea to always call "inner()" to allow for future subclassing.
package Employee;
use Moose;
extends 'Person';
has 'job_title' => ( is => 'rw' );
override 'display_name' => sub {
my $self = shift;
return super() . q{, } . $self->job_title();
};
The call to "super()" is almost the same as calling "$self->SUPER::display_name". The difference is that the arguments passed to the superclass's method will always be the same as the ones passed to the method modifier, and cannot be changed.
All arguments passed to "super()" are ignored, as are any changes made to @_ before "super()" is called.
after 'foo' => sub { };
Both "override" and "augment" are similar to "around" in that they can decide whether or not to call the method they modify before or after throwing an exception.
From the caller's perspective, an exception in a method modifier will look like the method it called threw an exception. However, method modifiers are just standard Perl subroutines. This means that they end up on the stack in stack traces as an additional frame.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.