Commit | Line | Data |
ceb8945d |
1 | |
2 | =pod |
3 | |
4 | =head1 NAME |
5 | |
6 | Moose::Cookbook::Recipe9 - Builder methods and lazy_build |
7 | |
8 | =head1 SYNOPSIS |
9 | |
10 | package BinaryTree; |
11 | use Moose; |
12 | |
13 | has 'node' => (is => 'rw', isa => 'Any'); |
14 | |
15 | has 'parent' => ( |
16 | is => 'rw', |
17 | isa => 'BinaryTree', |
18 | predicate => 'has_parent', |
19 | weak_ref => 1, |
20 | ); |
21 | |
22 | has 'left' => ( |
23 | is => 'rw', |
24 | isa => 'BinaryTree', |
25 | predicate => 'has_left', |
26 | lazy => 1, |
27 | builder => '_build_child_tree', |
28 | ); |
29 | |
30 | has 'right' => ( |
31 | is => 'rw', |
32 | isa => 'BinaryTree', |
33 | predicate => 'has_right', |
34 | lazy => 1, |
35 | builder => '_build_child_tree', |
36 | ); |
37 | |
38 | before 'right', 'left' => sub { |
39 | my ($self, $tree) = @_; |
40 | $tree->parent($self) if defined $tree; |
41 | }; |
42 | |
43 | sub _build_child_tree { |
44 | my $self = shift; |
45 | |
46 | return BinaryTree->new( parent => $self ); |
47 | } |
48 | |
49 | =head1 DESCRIPTION |
50 | |
51 | If you've already read L<Moose::Cookbook::Recipe3>, then this example |
52 | should look awfully familiar. In fact, all we've done here is replace |
53 | the attribute C<default> with a C<builder> method. |
54 | |
e89d3090 |
55 | In this particular case, the C<default> and C<builder> options act in |
56 | exactly the same way. When the C<left> or C<right> attribute get |
57 | method is called, Moose will call the builder method to initialize the |
58 | attribute. |
59 | |
60 | Note that Moose calls the builder method I<on the object which has the |
61 | attribute>. Here's an example in code: |
62 | |
63 | my $tree = BinaryTree->new(); |
64 | |
65 | my $left = $tree->left(); |
66 | |
67 | At this point, Moose will call C<< $tree->_build_child_tree() >> in |
68 | order to populate the C<left> attribute. If we had passed C<left> to |
69 | the original constructor, the builer would not be called. |
ceb8945d |
70 | |
71 | =head2 Subclassable |
72 | |
73 | There are some differences between C<default> and C<builder>. Because |
74 | C<builder> is called I<by name>, it goes through Perl's normal |
75 | inheritance system. This means that builder methods are both |
76 | inheritable and overrideable. |
77 | |
78 | For example, we might make a C<BinaryTree> subclass: |
79 | |
80 | package TrinaryTree; |
81 | use Moose; |
82 | |
83 | extends 'BinaryTree'; |
84 | |
85 | has 'middle' => ( |
86 | is => 'rw', |
87 | isa => 'BinaryTree', |
88 | predicate => 'has_middle', |
89 | lazy => 1, |
90 | builder => '_build_child_tree', |
91 | ); |
92 | |
93 | This doesn't quite work though. If you look closely at the |
94 | C<_build_child_tree> method defined in C<BinaryTree>, you'll notice |
95 | that it hard-codes a class name. Naughty us! |
96 | |
97 | Also, as a bonus, we'll pass C<@_> through, so subclasses can override |
98 | the method to pass additional options to the constructor. |
99 | |
100 | Good object-oriented code should allow itself to be subclassed |
101 | gracefully. Let's tweak C<_build_child_tree>: |
102 | |
7f785a28 |
103 | sub _build_child_tree { |
ceb8945d |
104 | my $self = shift; |
105 | |
106 | return (ref $self)->new( parent => $self, @_ ); |
107 | } |
108 | |
109 | Now C<_build_child_tree> can be gracefully inherited and overridden. |
110 | |
111 | =head2 Composable |
112 | |
113 | There's more to builders than just subclassing, though. The fact that |
114 | builders are called by name also makes them suitable for use in a |
115 | role. |
116 | |
117 | package HasAnimal; |
118 | use Moose::Role; |
119 | |
120 | requires '_build_animal'; |
121 | |
122 | has 'animal' => ( |
123 | is => 'ro', |
124 | isa => 'Animal', |
125 | lazy => 1, |
126 | builder => '_build_animal', |
127 | ); |
128 | |
129 | This role provides an animal attribute, but requires that the consumer |
130 | of the role provide a builder method it. |
131 | |
132 | package CatLover; |
133 | use Moose; |
134 | |
135 | with 'HasAnimal'; |
136 | |
137 | sub _build_animal { |
138 | return Cat->new(); |
139 | } |
140 | |
ceb8945d |
141 | =head2 The lazy_build shortcut |
142 | |
143 | The C<lazy_build> attribute parameter can be used as sugar to specify |
144 | a whole bunch of options at once. |
145 | |
146 | has 'animal' => ( |
147 | is => 'ro', |
148 | isa => 'Animal', |
149 | lazy_build => 1, |
150 | ); |
151 | |
152 | This is a shorthand for this: |
153 | |
154 | has 'animal' => ( |
155 | is => 'ro', |
156 | isa => 'Animal', |
157 | required => 1, |
158 | lazy => 1, |
159 | builder => '_build_animal', |
160 | predicate => 'has_animal', |
161 | clearer => 'clear_animal', |
162 | ); |
163 | |
164 | If your attribute starts with an underscore, Moose is smart and will |
165 | do the right thing with the C<predicate> and C<clearer>, making them |
166 | both start with an underscore. The C<builder> method I<always> starts |
167 | with an underscore, since you will want this to be private the vast |
168 | majority of the time. |
169 | |
398e7b2c |
170 | Note that the C<builder> method name is created by simply taking |
171 | "_build_" and appending the attribute name. This means that attributes |
172 | with a leading underscore like C<_animal> end up with a builder named |
173 | C<_build__animal>. |
174 | |
ceb8945d |
175 | =head1 CONCLUSION |
176 | |
177 | The C<builder> option is a more OO-friendly version of the C<default> |
178 | functionality. It also has the property of separating out the code |
179 | into a separate well-defined method. This alone makes it valuable. It |
180 | is quite ugly to jam a long default code reference into your attribute |
181 | definition. |
182 | |
183 | Here are some good rules for determining when to use C<builder> vs |
184 | C<default>. |
185 | |
186 | If the default value is a simple scalar that only needs to be |
187 | calculated once (or a constant), use C<default>. |
188 | |
189 | If the default value is an empty reference that needs to be wrapped in |
190 | a coderef like C<sub { [] }>, use C<default>. |
191 | |
192 | Otherwise, use C<builder>. |
193 | |
09b815aa |
194 | This ensures that your classes are easily subclassable, and also helps |
195 | keep crufty code out of your attribute definition blocks. |
196 | |
ceb8945d |
197 | =head1 AUTHOR |
198 | |
199 | Dave Rolsky E<lt>autarch@urth.orgE<gt> |
200 | |
201 | =head1 COPYRIGHT AND LICENSE |
202 | |
203 | Copyright 2006-2008 by Infinity Interactive, Inc. |
204 | |
205 | L<http://www.iinteractive.com> |
206 | |
207 | This library is free software; you can redistribute it and/or modify |
208 | it under the same terms as Perl itself. |
209 | |
210 | =cut |