lib/Moose/Manual/MethodModifiers.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 Moose::Manual::MethodModifiers - Moose's method modifiers
   6
   7 =head1 WHAT IS A METHOD MODIFIER?
   8
   9 Moose provides a feature called "method modifiers". You can also think
  10 of these as "hooks" or "advice".
  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 {
  19       print "    foo\n";
  20   }
  21
  22   before 'foo' => sub { print "about to call foo\n"; };
  23   after 'foo'  => sub { print "just called foo\n"; };
  24
  25   around 'foo' => sub {
  26       my $orig = shift;
  27       my $self = shift;
  28
  29       print "  I'm around foo\n";
  30
  31       $self->$orig(@_);
  32
  33       print "  I'm still around foo\n";
  34   };
  35
  36 Now if I call C<< Example->new->foo >> I'll get the following output:
  37
  38   about to call foo
  39     I'm around foo
  40       foo
  41     I'm still around foo
  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
  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.
  69
  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.
  73
  74 =head1 BEFORE, AFTER, AND AROUND
  75
  76 Method modifiers can be used to add behavior to a method that Moose
  77 generates for you, such as an attribute accessor:
  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
  90 prechecking on a method call. For example:
  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
  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.
 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
 109 An around modifier is more powerful than either a before or
 110 after modifier. It can modify the arguments being passed to the
 111 original method, and you can even decide to simply not call the
 112 original method at all. You can also modify the return value with an
 113 around modifier.
 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
 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
 135   before [qw(foo bar baz)] => sub {
 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
 145 actually matter. If the function name does matter, use something like this:
 146
 147   for my $func (qw(foo bar baz)) {
 148       before $func => sub {
 149           warn "$func was called!";
 150       };
 151   }
 152
 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
 162 to each one that matches. The same caveats apply as above. Using regular
 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
 166 methods with a special meaning to Moose or Perl, such as C<meta>, C<new>,
 167 C<BUILD>, C<DESTROY>, C<AUTOLOAD>, etc., as this could cause
 168 unintended (and hard to debug) problems.
 169
 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
 207       my $xml = "  <report>\n";
 208       $xml .= inner();
 209       $xml .= "  </report>\n";
 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>
 217     <report>
 218     </report>
 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
 233       my $xml = '    <income>' . $self->income . '</income>';
 234       $xml .= "\n";
 235       $xml .= '    <expenses>' . $self->expenses . '</expenses>';
 236       $xml .= "\n";
 237
 238       $xml .= inner() || q{};
 239
 240       return $xml;
 241   };
 242
 243 Now our report has some content:
 244
 245   <document>
 246     <report>
 247       <income>$10</income>
 248       <expenses>$8</expenses>
 249     </report>
 250   </document>
 251
 252 What makes this combination of C<augment> and C<inner()> special is
 253 that it allows us to have methods which are called from parent (least
 254 specific) to child (most specific). This inverts the normal
 255 inheritance pattern.
 256
 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.
 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
 304 Copyright 2008-2010 by Infinity Interactive, Inc.
 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