Moose::...difiers(3)

💖 Moose::Manual::MethodModifiers(3) 💖

okay bestie, this is the manual page for Moose::Manual::MethodModifiers from the User Contributed Perl Documentation. It's literally all about Moose's method modifiers, and this is part 1, so don't go anywhere. ✨

---

💅 NAME 💅

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

🌸 VERSION 🌸

version 2.4000

🦋 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. periodt.

🦋 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. iykyk.

👑 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. fr fr.

⭐ 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:

no cap, don't forget that semi-colon.

         after 'foo' => sub { };

💥 EXCEPTIONS AND STACK TRACES 💥

okay so bestie, let's talk about what happens when things go wrong 💀

• Throw an exception inside a before modifier and the method it modifies does not get called at all. Like, zero. Not even a little. It's over before it started 🙈
• Throw one inside an around modifier and whether the wrapped method ever runs is totally up to how you wrote that around — you're the one holding the controller, so it depends on your structure, fr fr
• Throw one inside an after modifier and, well, obviously it cannot stop the method it wraps from being called. The method already ran, babes. That ship sailed 🚢

Both override and augment are lowkey similar to around here: they get to decide whether they call the method they modify before or after they throw an exception. Main character choice energy 👑

Now, from the caller's point of view? An exception in a method modifier just looks like the method it called threw an exception. Simple. Clean. Except…

plot twist 🫠 method modifiers are just standard Perl subroutines. Which means they show up on the stack in stack traces as an extra frame. So when you're squinting at a traceback wondering "who is this mystery sub," it's probably your modifier. iykyk

---

⚠️ CAVEATS ⚠️

ngl, this is the part where I hold your hand and look you in the eye:

These method modification features do not work well with multiple inheritance, and that's because of how method resolution is performed in Perl. It's not a vibe thing, it's a Perl thing 😭

So what do you do?

• Experiment with a test program to make sure your class hierarchy actually works the way you expect 🧪
• or, more preferably, don't use multiple inheritance at all — roles can help with this, bestie, I promise 🫶

---

👑 AUTHORS 👑

Absolute legends, the whole squad, give them their flowers 💐

• Stevan Little <stevan@cpan.org>
• Dave Rolsky <autarch@urth.org>
• Jesse Luehrs <doy@cpan.org>
• Shawn M Moore <sartak@cpan.org>
• יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
• Karen Etheridge <ether@cpan.org>
• Florian Ragwitz <rafl@debian.org>
• Hans Dieter Pearcey <hdp@cpan.org>
• Chris Prather <chris@prather.org>
• Matt S Trout <mstrout@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. periodt 💅

---

and that's a wrap on this page, bestie 🎀 this was perl v5.42.0, dated 2025-07-25, and it came to you straight from the Moose::...difiers(3) manpage. go forth and modify some methods responsibly 💖✨🦋