Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Moose::Manual::MethodMUseriContributed Perl DMoose::Manual::MethodModifiers(3)

NAME
       Moose::Manual::MethodModifiers -	Moose's	method modifiers

VERSION
       version 2.2005

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.	They are often used in roles to	alter
       the behavior of methods in the classes that consume the role. 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 methods without
       modifying the definition	of those methods.

   Before and after Modifiers
       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.

   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.

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

   Wrapping multiple methods at	once
       "before", "after", and "around" can also	modify multiple	methods	at
       once. The simplest example of this is passing them as a list:

	 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!";
	     };
	 }

   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:

       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

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. 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":

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

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
       o   Stevan Little <stevan.little@iinteractive.com>

       o   Dave	Rolsky <autarch@urth.org>

       o   Jesse Luehrs	<doy@tozt.net>

       o   Shawn M Moore <code@sartak.org>

       o   xxxx	x<section>xx'xx	(Yuval Kogman) <nothingmuch@woobling.org>

       o   Karen Etheridge <ether@cpan.org>

       o   Florian Ragwitz <rafl@debian.org>

       o   Hans	Dieter Pearcey <hdp@weftsoar.net>

       o   Chris Prather <chris@prather.org>

       o   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.

perl v5.24.1			  2017-05-03 Moose::Manual::MethodModifiers(3)

NAME | VERSION | WHAT IS A METHOD MODIFIER? | WHY USE THEM? | BEFORE, AFTER, AND AROUND | INNER AND AUGMENT | OVERRIDE AND SUPER | SEMI-COLONS | EXCEPTIONS AND STACK TRACES | CAVEATS | AUTHORS | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Moose::Manual::MethodModifiers&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help