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>:
92 sub _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 =head2 The lazy_build shortcut
132 The C<lazy_build> attribute parameter can be used as sugar to specify
133 a whole bunch of options at once.
141 This is a shorthand for this:
148 builder => '_build_animal',
149 predicate => 'has_animal',
150 clearer => 'clear_animal',
153 If your attribute starts with an underscore, Moose is smart and will
154 do the right thing with the C<predicate> and C<clearer>, making them
155 both start with an underscore. The C<builder> method I<always> starts
156 with an underscore, since you will want this to be private the vast
157 majority of the time.
159 Note that the C<builder> method name is created by simply taking
160 "_build_" and appending the attribute name. This means that attributes
161 with a leading underscore like C<_animal> end up with a builder named
166 The C<builder> option is a more OO-friendly version of the C<default>
167 functionality. It also has the property of separating out the code
168 into a separate well-defined method. This alone makes it valuable. It
169 is quite ugly to jam a long default code reference into your attribute
172 Here are some good rules for determining when to use C<builder> vs
175 If the default value is a simple scalar that only needs to be
176 calculated once (or a constant), use C<default>.
178 If the default value is an empty reference that needs to be wrapped in
179 a coderef like C<sub { [] }>, use C<default>.
181 Otherwise, use C<builder>.
183 This ensures that your classes are easily subclassable, and also helps
184 keep crufty code out of your attribute definition blocks.
188 Dave Rolsky E<lt>autarch@urth.orgE<gt>
190 =head1 COPYRIGHT AND LICENSE
192 Copyright 2006-2008 by Infinity Interactive, Inc.
194 L<http://www.iinteractive.com>
196 This library is free software; you can redistribute it and/or modify
197 it under the same terms as Perl itself.