package Moose::Cookbook::Basics::Document_AugmentAndInner
# ABSTRACT: The augment modifier, which turns normal method overriding "inside-out"
__END__
=pod
=head1 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('') }
sub close_page { (shift)->append_body('') }
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('') }
sub create_footer { (shift)->append_body('') }
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('');
}
#
my $report_xml = TPSReport->new->create;
=head1 DESCRIPTION
This recipe shows how the C method modifier works. This
modifier reverses the normal subclass to parent method resolution
order. With an C modifier the I specific method is
called first. Each successive call to C descends the
inheritance tree, ending at the most specific subclass.
The C 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 C class.
We start with the least specific class, C. Its create
method contains a call to C:
sub create {
my $self = shift;
$self->open_page;
inner();
$self->close_page;
}
The C function is exported by C, and is like C
for augmented methods. When C is called, Moose finds the next
method in the chain, which is the C modifier in
C. You'll note that we can call
C 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 C class.
Finally, in the C class, the chain comes to an end:
augment 'create' => sub {
my $self = shift;
$self->create_tps_report;
inner();
};
We do call the C 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 C in the future.
=head1 CONCLUSION
The C 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.
=begin testing
my $tps_report = TPSReport->new;
isa_ok( $tps_report, 'TPSReport' );
is(
$tps_report->create,
q{},
'... got the right TPS report'
);
=end testing
=cut