Moose::Cookbook::Basics::Document_AugmentAndInner - The augment modifier, which turns normal method overriding "inside-out" |
Moose::Cookbook::Basics::Document_AugmentAndInner - The augment modifier, which turns normal method overriding ``inside-out''
version 2.1605
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;
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.
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.
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.
Moose::Cookbook::Basics::Document_AugmentAndInner - The augment modifier, which turns normal method overriding "inside-out" |