.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Moose::Cookbook::Basics::Document_AugmentAndInner 3pm"
.TH Moose::Cookbook::Basics::Document_AugmentAndInner 3pm "2012-06-28" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Moose::Cookbook::Basics::Document_AugmentAndInner \- The augment modifier, which turns normal method overriding "inside\-out"
.SH "VERSION"
.IX Header "VERSION"
version 2.0603
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& package Document::Page;
\& use Moose;
\&
\& has \*(Aqbody\*(Aq => ( is => \*(Aqrw\*(Aq, isa => \*(AqStr\*(Aq, default => sub {\*(Aq\*(Aq} );
\&
\& 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(\*(Aq\*(Aq) }
\& sub close_page { (shift)\->append_body(\*(Aq\*(Aq) }
\&
\& package Document::PageWithHeadersAndFooters;
\& use Moose;
\&
\& extends \*(AqDocument::Page\*(Aq;
\&
\& augment \*(Aqcreate\*(Aq => sub {
\& my $self = shift;
\& $self\->create_header;
\& inner();
\& $self\->create_footer;
\& };
\&
\& sub create_header { (shift)\->append_body(\*(Aq\*(Aq) }
\& sub create_footer { (shift)\->append_body(\*(Aq\*(Aq) }
\&
\& package TPSReport;
\& use Moose;
\&
\& extends \*(AqDocument::PageWithHeadersAndFooters\*(Aq;
\&
\& augment \*(Aqcreate\*(Aq => sub {
\& my $self = shift;
\& $self\->create_tps_report;
\& inner();
\& };
\&
\& sub create_tps_report {
\& (shift)\->append_body(\*(Aq\*(Aq);
\& }
\&
\& #
\& my $report_xml = TPSReport\->new\->create;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This recipe shows how the \f(CW\*(C`augment\*(C'\fR method modifier works. This
modifier reverses the normal subclass to parent method resolution
order. With an \f(CW\*(C`augment\*(C'\fR modifier the \fIleast\fR specific method is
called first. Each successive call to \f(CW\*(C`inner\*(C'\fR descends the
inheritance tree, ending at the most specific subclass.
.PP
The \f(CW\*(C`augment\*(C'\fR 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.
.PP
In the example above, we've created a set of document classes, with
the most specific being the \f(CW\*(C`TPSReport\*(C'\fR class.
.PP
We start with the least specific class, \f(CW\*(C`Document::Page\*(C'\fR. Its create
method contains a call to \f(CW\*(C`inner()\*(C'\fR:
.PP
.Vb 6
\& sub create {
\& my $self = shift;
\& $self\->open_page;
\& inner();
\& $self\->close_page;
\& }
.Ve
.PP
The \f(CW\*(C`inner\*(C'\fR function is exported by \f(CW\*(C`Moose\*(C'\fR, and is like \f(CW\*(C`super\*(C'\fR
for augmented methods. When \f(CW\*(C`inner\*(C'\fR is called, Moose finds the next
method in the chain, which is the \f(CW\*(C`augment\*(C'\fR modifier in
\&\f(CW\*(C`Document::PageWithHeadersAndFooters\*(C'\fR. You'll note that we can call
\&\f(CW\*(C`inner\*(C'\fR in our modifier:
.PP
.Vb 6
\& augment \*(Aqcreate\*(Aq => sub {
\& my $self = shift;
\& $self\->create_header;
\& inner();
\& $self\->create_footer;
\& };
.Ve
.PP
This finds the next most specific modifier, in the \f(CW\*(C`TPSReport\*(C'\fR class.
.PP
Finally, in the \f(CW\*(C`TPSReport\*(C'\fR class, the chain comes to an end:
.PP
.Vb 5
\& augment \*(Aqcreate\*(Aq => sub {
\& my $self = shift;
\& $self\->create_tps_report;
\& inner();
\& };
.Ve
.PP
We do call the \f(CW\*(C`inner\*(C'\fR 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 \f(CW\*(C`TPSReport\*(C'\fR in the future.
.SH "CONCLUSION"
.IX Header "CONCLUSION"
The \f(CW\*(C`augment\*(C'\fR 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.
.SH "AUTHOR"
.IX Header "AUTHOR"
Moose is maintained by the Moose Cabal, along with the help of many contributors. See \*(L"\s-1CABAL\s0\*(R" in Moose and \*(L"\s-1CONTRIBUTORS\s0\*(R" in Moose for details.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2012 by Infinity Interactive, Inc..
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.