Moose::Manual::MethodModifiers - phpMan

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

VERSION
    version 2.2200

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->job_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
    *   Stevan Little <stevan AT cpan.org>

    *   Dave Rolsky <autarch AT urth.org>

    *   Jesse Luehrs <doy AT cpan.org>

    *   Shawn M Moore <sartak AT cpan.org>

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

    *   Karen Etheridge <ether AT cpan.org>

    *   Florian Ragwitz <rafl AT debian.org>

    *   Hans Dieter Pearcey <hdp AT cpan.org>

    *   Chris Prather <chris AT prather.org>

    *   Matt S Trout <mstrout AT cpan.org>

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.