6 Moose::Cookbook::Recipe9 - Builder methods and lazy_build
13 has 'node' => (is => 'rw', isa => 'Any');
18 predicate => 'has_parent',
25 predicate => 'has_left',
27 builder => '_build_child_tree',
33 predicate => 'has_right',
35 builder => '_build_child_tree',
38 before 'right', 'left' => sub {
39 my ($self, $tree) = @_;
40 $tree->parent($self) if defined $tree;
43 sub _build_child_tree {
46 return BinaryTree->new( parent => $self );
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.
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
60 Note that Moose calls the builder method I<on the object which has the
61 attribute>. Here's an example in code:
63 my $tree = BinaryTree->new();
65 my $left = $tree->left();
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.
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.
78 For example, we might make a C<BinaryTree> subclass:
88 predicate => 'has_middle',
90 builder => '_build_child_tree',
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!
97 Also, as a bonus, we'll pass C<@_> through, so subclasses can override
98 the method to pass additional options to the constructor.
100 Good object-oriented code should allow itself to be subclassed
101 gracefully. Let's tweak C<_build_child_tree>:
103 sub _build_child_tree {
106 return (ref $self)->new( parent => $self, @_ );
109 Now C<_build_child_tree> can be gracefully inherited and overridden.
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
120 requires '_build_animal';
126 builder => '_build_animal',
129 This role provides an animal attribute, but requires that the consumer
130 of the role provide a builder method it.
141 =head2 The lazy_build shortcut
143 The C<lazy_build> attribute parameter can be used as sugar to specify
144 a whole bunch of options at once.
152 This is a shorthand for this:
159 builder => '_build_animal',
160 predicate => 'has_animal',
161 clearer => 'clear_animal',
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.
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
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
183 Here are some good rules for determining when to use C<builder> vs
186 If the default value is a simple scalar that only needs to be
187 calculated once (or a constant), use C<default>.
189 If the default value is an empty reference that needs to be wrapped in
190 a coderef like C<sub { [] }>, use C<default>.
192 Otherwise, use C<builder>.
194 This ensures that your classes are easily subclassable, and also helps
195 keep crufty code out of your attribute definition blocks.
199 Dave Rolsky E<lt>autarch@urth.orgE<gt>
201 =head1 COPYRIGHT AND LICENSE
203 Copyright 2006-2008 by Infinity Interactive, Inc.
205 L<http://www.iinteractive.com>
207 This library is free software; you can redistribute it and/or modify
208 it under the same terms as Perl itself.