NAME¶
Moose::Cookbook::Basics::Document_AugmentAndInner - The augment modifier, which
turns normal method overriding "inside-out"
VERSION¶
version 2.1213
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.little@iinteractive.com>
- •
- Dave Rolsky <autarch@urth.org>
- •
- Jesse Luehrs <doy@tozt.net>
- •
- Shawn M Moore <code@sartak.org>
- •
- XXXX XXX'XX (Yuval Kogman) <nothingmuch@woobling.org>
- •
- Karen Etheridge <ether@cpan.org>
- •
- Florian Ragwitz <rafl@debian.org>
- •
- Hans Dieter Pearcey <hdp@weftsoar.net>
- •
- Chris Prather <chris@prather.org>
- •
- Matt S Trout <mst@shadowcat.co.uk>
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.