---
name: "Moose::Cookbook::Basics::Document_AugmentAndInner"
section: "3pm"
platform: "linux"
package: "perl-moose"
version: "2.4001-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/Moose::Cookbook::Basics::Document_AugmentAndInner"
---

# Moose::Cookbook::Basics::Document\_AugmentAndInner(3pm)

The augment modifier, which turns normal method overriding "inside-out"

## NAME

Moose::Cookbook::Basics::Document\_AugmentAndInner - The augment modifier, which turns normal method overriding "inside-out"

## VERSION

version 2.4001

## SYNOPSIS

```
  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;
```

## DESCRIPTION

This recipe shows how the `"augment"` method modifier works. This modifier reverses the normal subclass to parent method resolution order. With an `"augment"` modifier the *least* specific method is called first. Each successive call to `"inner"` descends the inheritance tree, ending at the most specific subclass.

The `"augment"` modifier lets you design a parent class that can be extended in a specific way. The parent provides generic wrapper functionality, and the subclasses fill in the details.

In the example above, we've created a set of document classes, with the most specific being the `"TPSReport"` class.

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 is like `"super"` for augmented methods. When `"inner"` is called, Moose finds the next method in the chain, which is the `"augment"` modifier in `"Document::PageWithHeadersAndFooters"`. You'll note that we can call `"inner"` in our modifier:

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

This finds the next most specific modifier, 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();
  };
```

We do call the `"inner"` function one more time, but since there is no more specific subclass, this is a no-op. Making this call means we can easily subclass `"TPSReport"` in the future.

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

## AUTHORS

- •

  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.