GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  MOOSE::COOKBOOK::BASICS::DOCUMENT_AUGMENTANDINNER (3)

.ds Aq ’

NAME

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

CONTENTS

VERSION

version 2.1605

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

o Stevan Little <stevan.little@iinteractive.com>
o Dave Rolsky <autarch@urth.org>
o Jesse Luehrs <doy@tozt.net>
o Shawn M Moore <code@sartak.org>
o XXXX XXXXX (Yuval Kogman) <nothingmuch@woobling.org>
o Karen Etheridge <ether@cpan.org>
o Florian Ragwitz <rafl@debian.org>
o Hans Dieter Pearcey <hdp@weftsoar.net>
o Chris Prather <chris@prather.org>
o 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.

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 MOOSE::COOKBOOK::BASICS::DOCUMENT_AUGMENTANDINNER (3) 2016-02-16

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.