NAME

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

VERSION

       version 2.1005

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.

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

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)!

AUTHOR

       Moose is maintained by the Moose Cabal, along with the help of many contributors. See
       "CABAL" in Moose and "CONTRIBUTORS" in Moose for details.

COPYRIGHT AND LICENSE

       This software is copyright (c) 2013 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.