[gitmo/Moose.git] / lib / Moose / Manual / MethodModifiers.pod

=pod

=head1 NAME

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

=head1 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 C<< 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

=head1 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
L<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.

=head1 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 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,
I<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);
  };

C<before>, C<after>, and C<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 C<before> modifier to each of the C<foo>, C<bar>,
and C<baz> methods in the current class, just as though a separate
call to C<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!";
      };
  }

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 L<Class::MOP::Class/get_method_list>, 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. In particular, you should make sure to avoid wrapping
methods with a special meaning to Moose or Perl, such as C<meta>, C<new>,
C<BUILD>, C<DESTROY>, C<AUTOLOAD>, etc., as this could cause
unintended (and hard to debug) problems.

=head1 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 C<inner()>, which then calls the C<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 C<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 C<as_xml> on a Report object, we get something like this:

  <document>
    <report>
    </report>
  </document>

But we also called C<inner()> in C<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 C<augment> and C<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 C<Report::IncomeAndExpenses> we call C<inner()> again. If the
object is an instance of C<Report::IncomeAndExpenses> then this call is a
no-op, and just returns false. It's a good idea to always call C<inner()> to
allow for future subclassing.

=head1 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 C<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 C<super()> is almost the same as calling C<<
$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 C<super()> are ignored, as are any changes
made to C<@_> before C<super()> is called.

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

=head1 AUTHOR

Dave Rolsky E<lt>autarch@urth.orgE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright 2008-2009 by Infinity Interactive, Inc.

L<http://www.iinteractive.com>

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

=cut
Commit	Line	Data
92cd015f	1	=pod
	2
	3	=head1 NAME
	4
d67ce58f	5	Moose::Manual::MethodModifiers - Moose's method modifiers
92cd015f	6
	7	=head1 WHAT IS A METHOD MODIFIER?
	8
646e0fb0	9	Moose provides a feature called "method modifiers". You can also think
646e0fb0	10	of these as "hooks" or "advice".
92cd015f	11
	12	It's probably easiest to understand this feature with a few examples:
	13
	14	package Example;
	15
	16	use Moose;
	17
	18	sub foo {
909103e1	19	print " foo\n";
92cd015f	20	}
	21
	22	before 'foo' => sub { print "about to call foo\n"; };
08f950aa	23	after 'foo' => sub { print "just called foo\n"; };
92cd015f	24
	25	around 'foo' => sub {
	26	my $orig = shift;
	27	my $self = shift;
	28
909103e1	29	print " I'm around foo\n";
92cd015f	30
	31	$self->$orig(@_);
	32
909103e1	33	print " I'm still around foo\n";
92cd015f	34	};
	35
	36	Now if I call C<< Example->new->foo >> I'll get the following output:
	37
	38	about to call foo
909103e1	39	I'm around foo
	40	foo
	41	I'm still around foo
92cd015f	42	just called foo
	43
	44	You probably could have figured that out from the names "before",
	45	"after", and "around".
	46
	47	Also, as you can see, the before modifiers come before around
	48	modifiers, and after modifiers come last.
	49
	50	When there are multiple modifiers of the same type, the before and
	51	around modifiers run from the last added to the first, and after
	52	modifiers run from first added to last:
	53
	54	before 2
	55	before 1
	56	around 2
	57	around 1
	58	primary
	59	around 1
	60	around 2
	61	after 1
	62	after 2
	63
	64	=head1 WHY USE THEM?
	65
909103e1	66	Method modifiers have many uses. They are often used in roles to alter the
	67	behavior of methods in the classes that consume the role. See
	68	L<Moose::Manual::Roles> for more information about roles.
92cd015f	69
dab94063	70	Since modifiers are mostly useful in roles, some of the examples below
	71	are a bit artificial. They're intended to give you an idea of how
	72	modifiers work, but may not be the most natural usage.
92cd015f	73
	74	=head1 BEFORE, AFTER, AND AROUND
	75
dab94063	76	Method modifiers can be used to add behavior to a method that Moose
dab94063	77	generates for you, such as an attribute accessor:
92cd015f	78
	79	has 'size' => ( is => 'rw' );
	80
	81	before 'size' => sub {
	82	my $self = shift;
	83
	84	if (@_) {
	85	Carp::cluck('Someone is setting size');
	86	}
	87	};
	88
	89	Another use for the before modifier would be to do some sort of
6549b0d1	90	prechecking on a method call. For example:
92cd015f	91
	92	before 'size' => sub {
	93	my $self = shift;
	94
	95	die 'Cannot set size while the person is growing'
	96	if @_ && $self->is_growing;
	97	};
	98
646e0fb0	99	This lets us implement logical checks that don't make sense as type
	100	constraints. In particular, they're useful for defining logical rules
	101	about an object's state changes.
92cd015f	102
	103	Similarly, an after modifier could be used for logging an action that
	104	was taken.
	105
	106	Note that the return values of both before and after modifiers are
	107	ignored.
	108
909103e1	109	An around modifier is more powerful than either a before or
646e0fb0	110	after modifier. It can modify the arguments being passed to the
646e0fb0	111	original method, and you can even decide to simply not call the
dab94063	112	original method at all. You can also modify the return value with an
dab94063	113	around modifier.
92cd015f	114
	115	An around modifier receives the original method as its first argument,
	116	I<then> the object, and finally any arguments passed to the method.
	117
	118	around 'size' => sub {
	119	my $orig = shift;
	120	my $self = shift;
	121
	122	return $self->$orig()
	123	unless @_;
	124
	125	my $size = shift;
	126	$size = $size / 2
	127	if $self->likes_small_things();
	128
	129	return $self->$orig($size);
	130	};
	131
78946cf8	132	C<before>, C<after>, and C<around> can also modify multiple methods
	133	at once. The simplest example of this is passing them as a list:
	134
909103e1	135	before [qw(foo bar baz)] => sub {
78946cf8	136	warn "something is being called!";
	137	};
	138
	139	This will add a C<before> modifier to each of the C<foo>, C<bar>,
	140	and C<baz> methods in the current class, just as though a separate
	141	call to C<before> was made for each of them. The list can be passed
	142	either as a bare list, or as an arrayref. Note that the name of the
	143	function being modified isn't passed in in any way; this syntax is
	144	only intended for cases where the function being modified doesn't
909103e1	145	actually matter. If the function name does matter, use something like this:
78946cf8	146
	147	for my $func (qw(foo bar baz)) {
	148	before $func => sub {
	149	warn "$func was called!";
	150	};
	151	}
	152
78946cf8	153	In addition, you can specify a regular expression to indicate the
	154	methods to wrap, like so:
	155
	156	after qr/^command_/ => sub {
	157	warn "got a command";
	158	};
	159
	160	This will match the regular expression against each method name
	161	returned by L<Class::MOP::Class/get_method_list>, and add a modifier
909103e1	162	to each one that matches. The same caveats apply as above. Using regular
78946cf8	163	expressions to determine methods to wrap is quite a bit more powerful
	164	than the previous alternatives, but it's also quite a bit more
	165	dangerous. In particular, you should make sure to avoid wrapping
909103e1	166	methods with a special meaning to Moose or Perl, such as C<meta>, C<new>,
78946cf8	167	C<BUILD>, C<DESTROY>, C<AUTOLOAD>, etc., as this could cause
	168	unintended (and hard to debug) problems.
	169
92cd015f	170	=head1 INNER AND AUGMENT
	171
	172	Augment and inner are two halves of the same feature. The augment
	173	modifier provides a sort of inverted subclassing. You provide part of
	174	the implementation in a superclass, and then document that subclasses
	175	are expected to provide the rest.
	176
	177	The superclass calls C<inner()>, which then calls the C<augment>
	178	modifier in the subclass:
	179
	180	package Document;
	181
	182	use Moose;
	183
	184	sub as_xml {
	185	my $self = shift;
	186
	187	my $xml = "<document>\n";
	188	$xml .= inner();
	189	$xml .= "</document>\n";
	190
	191	return $xml;
	192	}
	193
	194	Using C<inner()> in this method makes it possible for one or more
	195	subclasses to then augment this method with their own specific
	196	implementation:
	197
	198	package Report;
	199
	200	use Moose;
	201
	202	extends 'Document';
	203
	204	augment 'as_xml' => sub {
	205	my $self = shift;
	206
909103e1	207	my $xml = " <report>\n";
92cd015f	208	$xml .= inner();
909103e1	209	$xml .= " </report>\n";
92cd015f	210
	211	return $xml;
	212	};
	213
	214	When we call C<as_xml> on a Report object, we get something like this:
	215
	216	<document>
909103e1	217	<report>
909103e1	218	</report>
92cd015f	219	</document>
	220
	221	But we also called C<inner()> in C<Report>, so we can continue
	222	subclassing and adding more content inside the document:
	223
	224	package Report::IncomeAndExpenses;
	225
	226	use Moose;
	227
	228	extends 'Report';
	229
	230	augment 'as_xml' => sub {
	231	my $self = shift;
	232
909103e1	233	my $xml = ' <income>' . $self->income . '</income>';
92cd015f	234	$xml .= "\n";
909103e1	235	$xml .= ' <expenses>' . $self->expenses . '</expenses>';
92cd015f	236	$xml .= "\n";
	237
	238	$xml .= inner() \|\| q{};
	239
	240	return $xml;
	241	};
	242
	243	Now our report has some content:
	244
	245	<document>
909103e1	246	<report>
	247	<income>$10</income>
	248	<expenses>$8</expenses>
	249	</report>
92cd015f	250	</document>
	251
	252	What makes this combination of C<augment> and C<inner()> special is
ce5e6e3c	253	that it allows us to have methods which are called from parent (least
646e0fb0	254	specific) to child (most specific). This inverts the normal
646e0fb0	255	inheritance pattern.
92cd015f	256
909103e1	257	Note that in C<Report::IncomeAndExpenses> we call C<inner()> again. If the
	258	object is an instance of C<Report::IncomeAndExpenses> then this call is a
	259	no-op, and just returns false. It's a good idea to always call C<inner()> to
	260	allow for future subclassing.
92cd015f	261
	262	=head1 OVERRIDE AND SUPER
	263
	264	Finally, Moose provides some simple sugar for Perl's built-in method
	265	overriding scheme. If you want to override a method from a parent
	266	class, you can do this with C<override>:
	267
	268	package Employee;
	269
	270	use Moose;
	271
	272	extends 'Person';
	273
	274	has 'job_title' => ( is => 'rw' );
	275
	276	override 'display_name' => sub {
	277	my $self = shift;
	278
	279	return super() . q{, } . $self->title();
	280	};
	281
	282	The call to C<super()> is almost the same as calling C<<
	283	$self->SUPER::display_name >>. The difference is that the arguments
	284	passed to the superclass's method will always be the same as the ones
	285	passed to the method modifier, and cannot be changed.
	286
	287	All arguments passed to C<super()> are ignored, as are any changes
	288	made to C<@_> before C<super()> is called.
	289
	290	=head1 SEMI-COLONS
	291
	292	Because all of these method modifiers are implemented as Perl
	293	functions, you must always end the modifier declaration with a
	294	semi-colon:
	295
	296	after 'foo' => sub { };
	297
	298	=head1 AUTHOR
	299
	300	Dave Rolsky E<lt>autarch@urth.orgE<gt>
	301
	302	=head1 COPYRIGHT AND LICENSE
	303
646e0fb0	304	Copyright 2008-2009 by Infinity Interactive, Inc.
92cd015f	305
	306	L<http://www.iinteractive.com>
	307
	308	This library is free software; you can redistribute it and/or modify
	309	it under the same terms as Perl itself.
	310
	311	=cut