1 package Moose::Cookbook::Basics::Document_AugmentAndInner
3 # ABSTRACT: The augment modifier, which turns normal method overriding "inside-out"
12 package Document::Page;
15 has 'body' => ( is => 'rw', isa => 'Str', default => sub {''} );
25 my ( $self, $appendage ) = @_;
26 $self->body( $self->body . $appendage );
29 sub open_page { (shift)->append_body('<page>') }
30 sub close_page { (shift)->append_body('</page>') }
32 package Document::PageWithHeadersAndFooters;
35 extends 'Document::Page';
37 augment 'create' => sub {
44 sub create_header { (shift)->append_body('<header/>') }
45 sub create_footer { (shift)->append_body('<footer/>') }
50 extends 'Document::PageWithHeadersAndFooters';
52 augment 'create' => sub {
54 $self->create_tps_report;
58 sub create_tps_report {
59 (shift)->append_body('<report type="tps"/>');
62 # <page><header/><report type="tps"/><footer/></page>
63 my $report_xml = TPSReport->new->create;
67 This recipe shows how the C<augment> method modifier works. This
68 modifier reverses the normal subclass to parent method resolution
69 order. With an C<augment> modifier the I<least> specific method is
70 called first. Each successive call to C<inner> descends the
71 inheritance tree, ending at the most specific subclass.
73 The C<augment> modifier lets you design a parent class that can be
74 extended in a specific way. The parent provides generic wrapper
75 functionality, and the subclasses fill in the details.
77 In the example above, we've created a set of document classes, with
78 the most specific being the C<TPSReport> class.
80 We start with the least specific class, C<Document::Page>. Its create
81 method contains a call to C<inner()>:
90 The C<inner> function is exported by C<Moose>, and is like C<super>
91 for augmented methods. When C<inner> is called, Moose finds the next
92 method in the chain, which is the C<augment> modifier in
93 C<Document::PageWithHeadersAndFooters>. You'll note that we can call
94 C<inner> in our modifier:
96 augment 'create' => sub {
100 $self->create_footer;
103 This finds the next most specific modifier, in the C<TPSReport> class.
105 Finally, in the C<TPSReport> class, the chain comes to an end:
107 augment 'create' => sub {
109 $self->create_tps_report;
113 We do call the C<inner> function one more time, but since there is no
114 more specific subclass, this is a no-op. Making this call means we can
115 easily subclass C<TPSReport> in the future.
119 The C<augment> modifier is a powerful tool for creating a set of
120 nested wrappers. It's not something you will need often, but when you
121 do, it is very handy.
125 my $tps_report = TPSReport->new;
126 isa_ok( $tps_report, 'TPSReport' );
130 q{<page><header/><report type="tps"/><footer/></page>},
131 '... got the right TPS report'