On Apache
Under GNU General Public License
2012-05-24 19:35 @38.107.179.240 Crawled by CCBot/1.0 (+http://www.commoncrawl.org/bot.html)
Moose::Manual::MethodModifiers(User Contributed Perl DocumentaMoose::Manual::MethodModifiers(3pm)
NAME
Moose::Manual::MethodModifiers - Moose's method modifiers
WHAT IS A METHOD MODIFIER?
Moose provides a feature called "method modifiers". You can also think of these as "hooks"
or "advice".
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
WHY USE THEM?
Method modifiers have many uses. One very common use is in roles. This lets roles alter
the behavior of methods in the classes that use them. See Moose::Manual::Roles for more
information about roles.
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.
BEFORE, AFTER, AND AROUND
Method modifiers can be used to add behavior to a method that Moose generates for you,
such as an attribute accessor:
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 is a bit more powerful than either a before or after modifier. It can
modify the arguments being passed to the original method, and you can even decide to
simply not call the original method at all. You can also modify the return value with an
around modifier.
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);
};
INNER AND AUGMENT
Augment and inner are two halves of the same feature. The augment modifier provides a sort
of inverted subclassing. You provide part of the implementation in a superclass, and then
document that subclasses are expected to provide the rest.
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.
OVERRIDE AND SUPER
Finally, Moose provides some simple sugar for Perl's built-in method overriding scheme. If
you want to override a method from a parent class, you can do this with "override":
package Employee;
use Moose;
extends 'Person';
has 'job_title' => ( is => 'rw' );
override 'display_name' => sub {
my $self = shift;
return super() . q{, } . $self->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.
SEMI-COLONS
Because all of these method modifiers are implemented as Perl functions, you must always
end the modifier declaration with a semi-colon:
after 'foo' => sub { };
AUTHOR
Dave Rolsky <autarch AT urth.org>
COPYRIGHT AND LICENSE
Copyright 2008-2009 by Infinity Interactive, Inc.
<http://www.iinteractive.com>
This library is free software; you can redistribute it and/or modify it under the same
terms as Perl itself.
perl v5.10.0 2009-04-07 Moose::Manual::MethodModifiers(3pm)
Generated by $Id: phpMan.php,v 4.49 2006/02/26 13:18:18 chedong Exp $ Author: Che Dong
On Apache
Under GNU General Public License
2012-05-24 19:35 @38.107.179.240 Crawled by CCBot/1.0 (+http://www.commoncrawl.org/bot.html)