Moose::Cookbook::Basics::DocumeUseruContribMoose::Cookbook::Basics::Document_AugmentAndInner(3pm)



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 AT iinteractive.com>

       ·   Dave Rolsky <autarch AT urth.org>

       ·   Jesse Luehrs <doy AT tozt.net>

       ·   Shawn M Moore <code AT sartak.org>

       ·   XXXX XXX'XX (Yuval Kogman) <nothingmuch AT woobling.org>

       ·   Karen Etheridge <ether AT cpan.org>

       ·   Florian Ragwitz <rafl AT debian.org>

       ·   Hans Dieter Pearcey <hdp AT weftsoar.net>

       ·   Chris Prather <chris AT prather.org>

       ·   Matt S Trout <mst AT shadowcat.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.



perl v5.20.1                               Moose::Cookbook::Basics::Document_AugmentAndInner(3pm)