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.

Around modifiers

An around modifier is 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.

Wrapping multiple methods at once

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:

Using regular expressions to select methods to wrap

In addition, you can specify a regular expression to indicate the methods to wrap, like so:

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.

Execution order of method modifiers and inheritance

When both a superclass and an inheriting class have the same method modifiers, the method modifiers of the inheriting class are wrapped around the method modifiers of the superclass, as the following example illustrates:

% 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

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:

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.

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:

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 { };

EXCEPTIONS AND STACK TRACES

An exception thrown in a before modifier will prevent the method it modifies from being called at all. An exception in an around modifier may prevent the modified method from being called, depending on how the around modifier is structured. An exception in an after modifier obviously cannot prevent the method it wraps from being called.

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.

CAVEATS

These method modification features do not work well with multiple inheritance, due to how method resolution is performed in Perl. Experiment with a test program to ensure your class hierarchy works as expected, or more preferably, don't use multiple inheritance (roles can help with this)!

AUTHORS

Stevan Little <stevan.little@iinteractive.com>

Dave Rolsky <autarch@urth.org>

Jesse Luehrs <doy@tozt.net>

Shawn M Moore <code@sartak.org>

יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>

Karen Etheridge <ether@cpan.org>

Florian Ragwitz <rafl@debian.org>

Hans Dieter Pearcey <hdp@weftsoar.net>

Chris Prather <chris@prather.org>

Matt S Trout <mst@shadowcat.co.uk>

COPYRIGHT AND LICENSE

This software is copyright (c) 2006 by Infinity Interactive, Inc.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

Module Install Instructions

To install Moose::Manual::MethodModifiers, simply copy and paste either of the commands in to your terminal

As a valued partner and proud supporter of MetaCPAN, StickerYou is
happy to offer a 10% discount on all Custom Stickers,
Business Labels, Roll Labels,
Vinyl Lettering or Custom Decals. StickerYou.com
is your one-stop shop to make your business stick.
Use code METACPAN10 at checkout to apply your discount.