Class::Method::Modifiers - provides Moose-like method modifiers
Version 0.07 released 12 Sep 07
package Class::Child;
use parent 'Class::Parent';
use Class::Method::Modifiers;
sub new_method { }
before 'old_method' => sub
{
carp "old_method is deprecated, use new_method";
};
around 'other_method' => sub
{
my $orig = shift;
my $ret = $orig->(@_);
return $ret =~ /\d/ ? $ret : lc $ret;
};
Method modifiers are a powerful feature from the CLOS (Common Lisp Object System) world.
In its most basic form, a method modifier is just a method that calls
$self->SUPER::foo(@_). I for one have trouble remembering that exact
invocation, so my classes seldom re-dispatch to their base classes. Very bad!
Class::Method::Modifiers provides four modifiers: before, around,
after, and guard. before and after are run just before and after
the method they modify, but can not really affect that original method.
guard is much like before, except that it can prevent the execution of
the original method. around is run in place of the original method, with a
hook to easily call that original method. See the MODIFIERS section for more
details on how the particular modifiers work.
One clear benefit of using Class::Method::Modifiers is that you can define
multiple modifiers in a single namespace. These separate modifiers don't need
to know about each other. This makes top-down design easy. Have a base class
that provides the skeleton methods of each operation, and have plugins modify
those methods to flesh out the specifics.
Parent classes need not know about Class::Method::Modifiers. This means you
should be able to modify methods in any subclass. See
the Term::VT102::ZeroBased manpage for an example of subclassing with CMM.
In short, Class::Method::Modifiers solves the problem of making sure you
call $self->SUPER::foo(@_), and provides a cleaner interface for it.
before is called before the method it is modifying. Its return value is
totally ignored. It receives the same @_ as the the method it is modifying
would have received. You can modify the @_ the original method will receive
by changing $_[0] and friends (or by changing anything inside a reference).
This is a feature!
guard is called before the method it is modifying, between any befores
and any arounds. If the guard returns a true value, then execution will
proceed as normal. If the guard returns a false value, then any further
guards, arounds, afters are not run. The method will appear to have
returned the canonical false value (undef in scalar context, the empty list
in list context). It receives the same @_ as the the method it is modifying
would have received. You can modify the @_ the original method will receive
by changing $_[0] and friends (or by changing anything inside a reference).
This is a feature!
Since guard is not exported by default, you must import either 'guard',
':guard', or ':all' when use-ing CMM. 'guard' will import only this one
modifier, ':guard' will import guard and before/after/around, and ':all' will
import guard, before, after, around, and anything else added in the future.
after is called after the method it is modifying. Its return value is
totally ignored. It receives the same @_ as the the method it is modifying
received, mostly. The original method can modify @_ (such as by changing
$_[0] or references) and after will see the modified version. If you
don't like this behavior, specify both a before and after, and copy the
@_ during before for after to use.
around is called instead of the method it is modifying. The method you're
overriding is passed in as the first argument (called $orig by convention).
Watch out for contextual return values of $orig.
You can use around to:
$orig a different @_
around 'method' => sub
{
my $orig = shift; my $self = shift;
$orig->($self, reverse @_);
};
$orig
around 'method' => sub
{
my $orig = shift;
ucfirst $orig->(@_);
};
$orig -- conditionally
around 'method' => sub
{
my $orig = shift;
return $orig->(@_) if time() % 2;
return "no dice, captain";
};
All three normal modifiers; before, after, and around; are exported
into your namespace by default. guard is imported only if you ask for it
(such as by use Class::Method::Modifiers ':guard' or ':all'. You may
use Class::Method::Modifiers () to avoid thrashing your namespace. I may
steal more features from Moose, namely super, override, inner,
augment, and whatever the Moose folks come up with next.
Note that the syntax and semantics for these modifiers is directly borrowed from Moose (the implementations, however, are not).
the Class::Trigger manpage shares a few similarities with Class::Method::Modifiers,
and they even have some overlap in purpose -- both can be used to implement
highly pluggable applications. The difference is that the Class::Trigger manpage
provides a mechanism for easily letting parent classes to invoke hooks defined
by other code. Class::Method::Modifiers provides a way of
overriding/augmenting methods safely, and the parent class need not know about
it.
It is erroneous to modify a method that doesn't exist in your class's inheritance hierarchy. If this occurs, an exception will be thrown when the method is invoked.
It doesn't yet play well with caller. There are some todo tests for this.
Don't get your hopes up though!
Moose, the Class::Trigger manpage, the Class::MOP::Method::Wrapped manpage, the MRO::Compat manpage, CLOS
Shawn M Moore, <sartak at gmail.com>
Calling $orig twice in an around modifier is prone to breakage. Moose
supports this, I currently don't.
Please report any bugs through RT: email
bug-class-method-modifiers at rt.cpan.org, or browse to
http://rt.cpan.org/NoAuth/ReportBug.html.
You can find this documentation for this module with the perldoc command.
perldoc Class::Method::Modifiers
You can also look for information at:
Thanks to Stevan Little for Moose, I would never have known about method modifiers otherwise.
Thanks to Matt Trout and Stevan Little for their advice.
Copyright 2007 Shawn M Moore.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.