1 package Moose::Cookbook::Basics::BankAccount_MethodModifiersAndSubclassing;
3 # ABSTRACT: Demonstrates the use of method modifiers in a subclass
15 has 'balance' => ( isa => 'Int', is => 'rw', default => 0 );
18 my ( $self, $amount ) = @_;
19 $self->balance( $self->balance + $amount );
23 my ( $self, $amount ) = @_;
24 my $current_balance = $self->balance();
25 ( $current_balance >= $amount )
26 || confess "Account overdrawn";
27 $self->balance( $current_balance - $amount );
30 package CheckingAccount;
33 extends 'BankAccount';
35 has 'overdraft_account' => ( isa => 'BankAccount', is => 'rw' );
37 before 'withdraw' => sub {
38 my ( $self, $amount ) = @_;
39 my $overdraft_amount = $amount - $self->balance();
40 if ( $self->overdraft_account && $overdraft_amount > 0 ) {
41 $self->overdraft_account->withdraw($overdraft_amount);
42 $self->deposit($overdraft_amount);
48 The first recipe demonstrated how to build very basic Moose classes,
49 focusing on creating and manipulating attributes. The objects in that
50 recipe were very data-oriented, and did not have much in the way of
51 behavior (i.e. methods). In this recipe, we expand upon the concepts
52 from the first recipe to include some real behavior. In particular, we
53 show how you can use a method modifier to implement new behavior for a
56 The classes in the SYNOPSIS show two kinds of bank account. A simple
57 bank account has one attribute, the balance, and two behaviors,
58 depositing and withdrawing money.
60 We then extend the basic bank account in the CheckingAccount
61 class. This class adds another attribute, an overdraft account. It
62 also adds overdraft protection to the withdraw method. If you try to
63 withdraw more than you have, the checking account attempts to
64 reconcile the difference by withdrawing money from the overdraft
67 The first class, B<BankAccount>, introduces a new attribute feature, a
70 has 'balance' => ( isa => 'Int', is => 'rw', default => 0 );
72 This says that a B<BankAccount> has a C<balance> attribute, which has
73 an C<Int> type constraint, a read/write accessor, and a default value
74 of C<0>. This means that every instance of B<BankAccount> that is
75 created will have its C<balance> slot initialized to C<0>, unless some
76 other value is provided to the constructor.
78 The C<deposit> and C<withdraw> methods should be fairly
79 self-explanatory, as they are just plain old Perl 5 OO. (2)
81 As you know from the first recipe, the keyword C<extends> sets a
82 class's superclass. Here we see that B<CheckingAccount> C<extends>
83 B<BankAccount>. The next line introduces yet another new attribute
84 feature, class-based type constraints:
86 has 'overdraft_account' => ( isa => 'BankAccount', is => 'rw' );
88 Up until now, we have only seen the C<Int> type constraint, which (as
89 we saw in the first recipe) is a builtin type constraint. The
90 C<BankAccount> type constraint is new, and was actually defined the
91 moment we created the B<BankAccount> class itself. In fact, Moose
92 creates a corresponding type constraint for every class in your
95 This means that in the first recipe, constraints for both C<Point> and
96 C<Point3D> were created. In this recipe, both C<BankAccount> and
97 C<CheckingAccount> type constraints are created automatically. Moose
98 does this as a convenience so that your classes and type constraint
99 can be kept in sync with one another. In short, Moose makes sure that
100 it will just DWIM (4).
102 In B<CheckingAccount>, we see another method modifier, the C<before>
105 before 'withdraw' => sub {
106 my ( $self, $amount ) = @_;
107 my $overdraft_amount = $amount - $self->balance();
108 if ( $self->overdraft_account && $overdraft_amount > 0 ) {
109 $self->overdraft_account->withdraw($overdraft_amount);
110 $self->deposit($overdraft_amount);
114 Just as with the C<after> modifier from the first recipe, Moose will
115 handle calling the superclass method (in this case C<<
116 BankAccount->withdraw >>).
118 The C<before> modifier will (obviously) run I<before> the code from
119 the superclass is run. Here, C<before> modifier implements overdraft
120 protection by first checking if there are available funds in the
121 checking account. If not (and if there is an overdraft account
122 available), it transfers the amount needed into the checking
125 As with the method modifier in the first recipe, we could use
126 C<SUPER::> to get the same effect:
129 my ( $self, $amount ) = @_;
130 my $overdraft_amount = $amount - $self->balance();
131 if ( $self->overdraft_account && $overdraft_amount > 0 ) {
132 $self->overdraft_account->withdraw($overdraft_amount);
133 $self->deposit($overdraft_amount);
135 $self->SUPER::withdraw($amount);
138 The benefit of taking the method modifier approach is we do not need
139 to remember to call C<SUPER::withdraw> and pass it the C<$amount>
140 argument when writing C<< CheckingAccount->withdraw >>.
142 This is actually more than just a convenience for forgetful
143 programmers. Using method modifiers helps isolate subclasses from
144 changes in the superclasses. For instance, if B<<
145 BankAccount->withdraw >> were to add an additional argument of some
146 kind, the version of B<< CheckingAccount->withdraw >> which uses
147 C<SUPER::withdraw> would not pass that extra argument correctly,
148 whereas the method modifier version would automatically pass along all
151 Just as with the first recipe, object instantiation uses the C<new>
152 method, which accepts named parameters.
154 my $savings_account = BankAccount->new( balance => 250 );
156 my $checking_account = CheckingAccount->new(
158 overdraft_account => $savings_account,
161 And as with the first recipe, a more in-depth example can be found in
162 the F<t/recipes/moose_cookbook_basics_recipe2.t> test file.
166 This recipe expanded on the basic concepts from the first recipe with
167 a more "real world" use case.
175 If you're paying close attention, you might realize that there's a
176 circular loop waiting to happen here. A smarter example would have to
177 make sure that we don't accidentally create a loop between the
178 checking account and its overdraft account.
182 Note that for simple methods like these, which just manipulate some
183 single piece of data, it is often not necessary to write them at all.
184 For instance, C<deposit> could be implemented via the C<inc> native
185 delegation for counters - see
186 L<Moose::Meta::Attribute::Native::Trait::Counter> for more specifics,
187 and L<Moose::Meta::Attribute::Native> for a broader overview.
191 In reality, this creation is sensitive to the order in which modules
192 are loaded. In more complicated cases, you may find that you need to
193 explicitly declare a class type before the corresponding class is
198 Moose does not attempt to encode a class's is-a relationships within
199 the type constraint hierarchy. Instead, Moose just considers the class
200 type constraint to be a subtype of C<Object>, and specializes the
201 constraint check to allow for subclasses. This means that an instance
202 of B<CheckingAccount> will pass a C<BankAccount> type constraint
203 successfully. For more details, please refer to the
204 L<Moose::Util::TypeConstraints> documentation.
208 If the overdraft account does not have the amount needed, it will
209 throw an error. Of course, the overdraft account could also have
210 overdraft protection. See note 1.
214 =head1 ACKNOWLEDGMENT
216 The BankAccount example in this recipe is directly taken from the
217 examples in this chapter of "Practical Common Lisp":
219 L<http://www.gigamonkeys.com/book/object-reorientation-generic-functions.html>
226 $savings_account = BankAccount->new( balance => 250 );
227 isa_ok( $savings_account, 'BankAccount' );
229 is( $savings_account->balance, 250, '... got the right savings balance' );
232 $savings_account->withdraw(50);
235 '... withdrew from savings successfully'
237 is( $savings_account->balance, 200,
238 '... got the right savings balance after withdrawal' );
240 $savings_account->deposit(150);
241 is( $savings_account->balance, 350,
242 '... got the right savings balance after deposit' );
246 my $checking_account = CheckingAccount->new(
248 overdraft_account => $savings_account
250 isa_ok( $checking_account, 'CheckingAccount' );
251 isa_ok( $checking_account, 'BankAccount' );
253 is( $checking_account->overdraft_account, $savings_account,
254 '... got the right overdraft account' );
256 is( $checking_account->balance, 100,
257 '... got the right checkings balance' );
261 $checking_account->withdraw(50);
264 '... withdrew from checking successfully'
266 is( $checking_account->balance, 50,
267 '... got the right checkings balance after withdrawal' );
268 is( $savings_account->balance, 350,
269 '... got the right savings balance after checking withdrawal (no overdraft)'
274 $checking_account->withdraw(200);
277 '... withdrew from checking successfully'
279 is( $checking_account->balance, 0,
280 '... got the right checkings balance after withdrawal' );
281 is( $savings_account->balance, 200,
282 '... got the right savings balance after overdraft withdrawal' );
286 my $checking_account = CheckingAccount->new(
289 # no overdraft account
291 isa_ok( $checking_account, 'CheckingAccount' );
292 isa_ok( $checking_account, 'BankAccount' );
294 is( $checking_account->overdraft_account, undef,
295 '... no overdraft account' );
297 is( $checking_account->balance, 100,
298 '... got the right checkings balance' );
302 $checking_account->withdraw(50);
305 '... withdrew from checking successfully'
307 is( $checking_account->balance, 50,
308 '... got the right checkings balance after withdrawal' );
312 $checking_account->withdraw(200);
315 '... withdrawal failed due to attempted overdraft'
317 is( $checking_account->balance, 50,
318 '... got the right checkings balance after withdrawal failure' );