Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Moose::Cookbook::BasicUserMContriCutedoPerlBDocumentocument_AugmentAndInner(3)

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

VERSION
       version 2.2005

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	x<section>xx'xx	(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.

perl v5.24.1		  Moose::Cookbook::Basics::Document_AugmentAndInner(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | CONCLUSION | AUTHORS | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Moose::Cookbook::Basics::Document_AugmentAndInner&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help