lib/Moose/Cookbook/Basics/Recipe9.pod

   1
   2 =pod
   3
   4 =head1 NAME
   5
   6 Moose::Cookbook::Basics::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::Basics::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
  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.
  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
 103   sub _build_child_tree {
 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
 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
 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
 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
 194 This ensures that your classes are easily subclassable, and also helps
 195 keep crufty code out of your attribute definition blocks.
 196
 197 =head1 AUTHOR
 198
 199 Dave Rolsky E<lt>autarch@urth.orgE<gt>
 200
 201 =head1 COPYRIGHT AND LICENSE
 202
 203 Copyright 2006-2009 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