Moose::...AndInner(3)

💖 Moose::Cookbook::Basics::Document_AugmentAndInner 💖

okay so bestie, buckle up — this is Moose::Cookbook::Basics::Document_AugmentAndInner, a page from the User Contributed Perl Documentation collection, and it's all about the augment modifier. the vibe? it literally turns normal method overriding inside-out. no cap. 🦋

---

✨ VERSION ✨

version 2.4000 — she's giving 2.4000 and she's proud of it 💅

---

🌸 SYNOPSIS 🌸

here's the whole thing, exactly as it lives, no edits, we don't touch the code in this house:

package Document::Page;
use Moose;

has 'body' => ( is => 'rw', isa => 'Str', default => sub {''} );

sub create {
    my $self = shift;
    $self->open_page;
    inner();
    $self->close_page;
}

sub append_body {
    my ( $self, $appendage ) = @_;
    $self->body( $self->body . $appendage );
}

sub open_page  { (shift)->append_body('<page>') }
sub close_page { (shift)->append_body('</page>') }

package Document::PageWithHeadersAndFooters;
use Moose;

extends 'Document::Page';

augment 'create' => sub {
    my $self = shift;
    $self->create_header;
    inner();
    $self->create_footer;
};

sub create_header { (shift)->append_body('<header/>') }
sub create_footer { (shift)->append_body('<footer/>') }

package TPSReport;
use Moose;

extends 'Document::PageWithHeadersAndFooters';

augment 'create' => sub {
    my $self = shift;
    $self->create_tps_report;
    inner();
};

sub create_tps_report {
    (shift)->append_body('<report type="tps"/>');
}

# <page><header/><report type="tps"/><footer/></page>
my $report_xml = TPSReport->new->create;

like… look at that final comment. # <page><header/><report type="tps"/><footer/></page> — she ate and left no crumbs. 🔥

---

💜 DESCRIPTION 💜

so this recipe is a whole demo of how the augment method modifier works. and the way that it works?? it literally reverses the normal subclass to parent method resolution order. yeah. it flips it. 🙈

with an augment modifier, the least specific method gets called first. then every successive call to inner descends the inheritance tree, all the way down, ending at the most specific subclass. it's giving reverse-birthday-cake, you start at the frosting and end at the sponge. 🎂

the augment modifier lets you design a parent class that can be extended in one specific way. the parent brings the generic wrapper functionality, and the subclasses fill in the details. teamwork, bestie. 🫶

in the example up there, we've made a little set of document classes, and the most specific one is the TPSReport class. very corporate. very iconic.

we start with the least specific class, Document::Page. its create method contains a call to inner():

sub create {
    my $self = shift;
    $self->open_page;
    inner();
    $self->close_page;
}

the inner function is exported by Moose, and honestly? it's like super for augmented methods. iykyk. when inner gets called, Moose finds the next method in the chain, which is the augment modifier in Document::PageWithHeadersAndFooters. and note — you absolutely can call inner inside your modifier:

augment 'create' => sub {
    my $self = shift;
    $self->create_header;
    inner();
    $self->create_footer;
};

and this one finds the next most specific modifier, over in the TPSReport class. 👑

finally, in the TPSReport class, the chain comes to an end:

augment 'create' => sub {
    my $self = shift;
    $self->create_tps_report;
    inner();
};

so yeah, we do call the inner function one more time, but since there is no more specific subclass, this is a no-op. and we still make that call on purpose, because it means we can easily subclass TPSReport in the future. future-proofing, bestie. main character planning energy. 💅

---

🌈 CONCLUSION 🌈

the augment modifier is a powerful tool for creating a set of nested wrappers. it's not something you will need often, but when you do, it is very handy. like a little niche superpower you pull out at the exact right moment. ⭐

---

🎀 AUTHORS 🎀

look at this lineup, the whole friend group came through:

• 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.

so like, go off, remix it, redistribute it, it's all above board. 🍓

---

and that's the whole page bestie!! perl v5.42.0 came through with this one on 2025-07-25, and yes, Moose::...AndInner(3) really is the name on the tin — mwah, bye!! 💖✨🧚