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> act exactly the
56 same. When the C<left> or C<right> attribute is first accessed before
57 it has been set, Moose will call the specified C<builder> method to
58 populate the attribute.
62 There are some differences between C<default> and C<builder>. Because
63 C<builder> is called I<by name>, it goes through Perl's normal
64 inheritance system. This means that builder methods are both
65 inheritable and overrideable.
67 For example, we might make a C<BinaryTree> subclass:
77 predicate => 'has_middle',
79 builder => '_build_child_tree',
82 This doesn't quite work though. If you look closely at the
83 C<_build_child_tree> method defined in C<BinaryTree>, you'll notice
84 that it hard-codes a class name. Naughty us!
86 Also, as a bonus, we'll pass C<@_> through, so subclasses can override
87 the method to pass additional options to the constructor.
89 Good object-oriented code should allow itself to be subclassed
90 gracefully. Let's tweak C<_build_child_tree>:
95 return (ref $self)->new( parent => $self, @_ );
98 Now C<_build_child_tree> can be gracefully inherited and overridden.
102 There's more to builders than just subclassing, though. The fact that
103 builders are called by name also makes them suitable for use in a
109 requires '_build_animal';
115 builder => '_build_animal',
118 This role provides an animal attribute, but requires that the consumer
119 of the role provide a builder method it.
130 This simply could not be done using a C<default>.
132 =head2 The lazy_build shortcut
134 The C<lazy_build> attribute parameter can be used as sugar to specify
135 a whole bunch of options at once.
143 This is a shorthand for this:
150 builder => '_build_animal',
151 predicate => 'has_animal',
152 clearer => 'clear_animal',
155 If your attribute starts with an underscore, Moose is smart and will
156 do the right thing with the C<predicate> and C<clearer>, making them
157 both start with an underscore. The C<builder> method I<always> starts
158 with an underscore, since you will want this to be private the vast
159 majority of the time.
163 The C<builder> option is a more OO-friendly version of the C<default>
164 functionality. It also has the property of separating out the code
165 into a separate well-defined method. This alone makes it valuable. It
166 is quite ugly to jam a long default code reference into your attribute
169 Here are some good rules for determining when to use C<builder> vs
172 If the default value is a simple scalar that only needs to be
173 calculated once (or a constant), use C<default>.
175 If the default value is an empty reference that needs to be wrapped in
176 a coderef like C<sub { [] }>, use C<default>.
178 Otherwise, use C<builder>.
182 Dave Rolsky E<lt>autarch@urth.orgE<gt>
184 =head1 COPYRIGHT AND LICENSE
186 Copyright 2006-2008 by Infinity Interactive, Inc.
188 L<http://www.iinteractive.com>
190 This library is free software; you can redistribute it and/or modify
191 it under the same terms as Perl itself.