local-lib5/man/man3/Moose::Cookbook::Basics::Recipe6.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Moose::Cookbook::Basics::Recipe6 3"
 132 .TH Moose::Cookbook::Basics::Recipe6 3 "2009-03-14" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Moose::Cookbook::Basics::Recipe6 \- The augment/inner example
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 2
 138 \&  package Document::Page;
 139 \&  use Moose;
 140 .Ve
 141 .PP
 142 .Vb 1
 143 \&  has 'body' => ( is => 'rw', isa => 'Str', default => sub {''} );
 144 .Ve
 145 .PP
 146 .Vb 6
 147 \&  sub create {
 148 \&      my $self = shift;
 149 \&      $self\->open_page;
 150 \&      inner();
 151 \&      $self\->close_page;
 152 \&  }
 153 .Ve
 154 .PP
 155 .Vb 4
 156 \&  sub append_body {
 157 \&      my ( $self, $appendage ) = @_;
 158 \&      $self\->body( $self\->body . $appendage );
 159 \&  }
 160 .Ve
 161 .PP
 162 .Vb 2
 163 \&  sub open_page  { (shift)\->append_body('<page>') }
 164 \&  sub close_page { (shift)\->append_body('</page>') }
 165 .Ve
 166 .PP
 167 .Vb 2
 168 \&  package Document::PageWithHeadersAndFooters;
 169 \&  use Moose;
 170 .Ve
 171 .PP
 172 .Vb 1
 173 \&  extends 'Document::Page';
 174 .Ve
 175 .PP
 176 .Vb 6
 177 \&  augment 'create' => sub {
 178 \&      my $self = shift;
 179 \&      $self\->create_header;
 180 \&      inner();
 181 \&      $self\->create_footer;
 182 \&  };
 183 .Ve
 184 .PP
 185 .Vb 2
 186 \&  sub create_header { (shift)\->append_body('<header/>') }
 187 \&  sub create_footer { (shift)\->append_body('<footer/>') }
 188 .Ve
 189 .PP
 190 .Vb 2
 191 \&  package TPSReport;
 192 \&  use Moose;
 193 .Ve
 194 .PP
 195 .Vb 1
 196 \&  extends 'Document::PageWithHeadersAndFooters';
 197 .Ve
 198 .PP
 199 .Vb 5
 200 \&  augment 'create' => sub {
 201 \&      my $self = shift;
 202 \&      $self\->create_tps_report;
 203 \&      inner();
 204 \&  };
 205 .Ve
 206 .PP
 207 .Vb 3
 208 \&  sub create_tps_report {
 209 \&      (shift)\->append_body('<report type="tps"/>');
 210 \&  }
 211 .Ve
 212 .PP
 213 .Vb 2
 214 \&  # <page><header/><report type="tps"/><footer/></page>
 215 \&  my $report_xml = TPSReport\->new\->create;
 216 .Ve
 217 .SH "DESCRIPTION"
 218 .IX Header "DESCRIPTION"
 219 This recipe shows how the \f(CW\*(C`augment\*(C'\fR method modifier works. This
 220 modifier reverses the normal subclass to parent method resolution
 221 order. With an \f(CW\*(C`augment\*(C'\fR modifier the \fIleast\fR specific method is
 222 called first. Each successive call to \f(CW\*(C`inner\*(C'\fR descends the
 223 inheritance tree, ending at the most specific subclass.
 224 .PP
 225 The \f(CW\*(C`augment\*(C'\fR modifier lets you design a parent class that can be
 226 extended in a specific way. The parent provides generic wrapper
 227 functionality, and the subclasses fill in the details.
 228 .PP
 229 In the example above, we've created a set of document classes, with
 230 the most specific being the \f(CW\*(C`TPSReport\*(C'\fR class.
 231 .PP
 232 We start with the least specific class, \f(CW\*(C`Document::Page\*(C'\fR. Its create
 233 method contains a call to \f(CW\*(C`inner()\*(C'\fR:
 234 .PP
 235 .Vb 6
 236 \&  sub create {
 237 \&      my $self = shift;
 238 \&      $self\->open_page;
 239 \&      inner();
 240 \&      $self\->close_page;
 241 \&  }
 242 .Ve
 243 .PP
 244 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
 245 for augmented methods. When \f(CW\*(C`inner\*(C'\fR is called, Moose finds the next
 246 method in the chain, which is the \f(CW\*(C`augment\*(C'\fR modifier in
 247 \&\f(CW\*(C`Document::PageWithHeadersAndFooters\*(C'\fR. You'll note that we can call
 248 \&\f(CW\*(C`inner\*(C'\fR in our modifier:
 249 .PP
 250 .Vb 6
 251 \&  augment 'create' => sub {
 252 \&      my $self = shift;
 253 \&      $self\->create_header;
 254 \&      inner();
 255 \&      $self\->create_footer;
 256 \&  };
 257 .Ve
 258 .PP
 259 This finds the next most specific modifier, in the \f(CW\*(C`TPSReport\*(C'\fR class.
 260 .PP
 261 Finally, in the \f(CW\*(C`TPSReport\*(C'\fR class, the chain comes to an end:
 262 .PP
 263 .Vb 5
 264 \&  augment 'create' => sub {
 265 \&      my $self = shift;
 266 \&      $self\->create_tps_report;
 267 \&      inner();
 268 \&  };
 269 .Ve
 270 .PP
 271 We do call the \f(CW\*(C`inner\*(C'\fR function one more time, but since there is no
 272 more specific subclass, this is a no\-op. Making this call means we can
 273 easily subclass \f(CW\*(C`TPSReport\*(C'\fR in the future.
 274 .SH "CONCLUSION"
 275 .IX Header "CONCLUSION"
 276 The \f(CW\*(C`augment\*(C'\fR modifier is a powerful tool for creating a set of
 277 nested wrappers. It's not something you will need often, but when you
 278 do it is very handy.
 279 .SH "AUTHOR"
 280 .IX Header "AUTHOR"
 281 Stevan Little <stevan@iinteractive.com>
 282 .PP
 283 Dave Rolsky <autarch@urth.org>
 284 .SH "COPYRIGHT AND LICENSE"
 285 .IX Header "COPYRIGHT AND LICENSE"
 286 Copyright 2007\-2009 by Infinity Interactive, Inc.
 287 .PP
 288 <http://www.iinteractive.com>
 289 .PP
 290 This library is free software; you can redistribute it and/or modify
 291 it under the same terms as Perl itself.