lib/Moose/Cookbook/Recipe9.pod

   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
  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.
  59
  60 =head2 Subclassable
  61
  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.
  66
  67 For example, we might make a C<BinaryTree> subclass:
  68
  69   package TrinaryTree;
  70   use Moose;
  71
  72   extends 'BinaryTree';
  73
  74   has 'middle' => (
  75       is        => 'rw',
  76       isa       => 'BinaryTree',
  77       predicate => 'has_middle',
  78       lazy      => 1,
  79       builder   => '_build_child_tree',
  80   );
  81
  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!
  85
  86 Also, as a bonus, we'll pass C<@_> through, so subclasses can override
  87 the method to pass additional options to the constructor.
  88
  89 Good object-oriented code should allow itself to be subclassed
  90 gracefully. Let's tweak C<_build_child_tree>:
  91
  92   sub _build_child_tree {
  93       my $self = shift;
  94
  95       return (ref $self)->new( parent => $self, @_ );
  96   }
  97
  98 Now C<_build_child_tree> can be gracefully inherited and overridden.
  99
 100 =head2 Composable
 101
 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
 104 role.
 105
 106   package HasAnimal;
 107   use Moose::Role;
 108
 109   requires '_build_animal';
 110
 111   has 'animal' => (
 112       is      => 'ro',
 113       isa     => 'Animal',
 114       lazy    => 1,
 115       builder => '_build_animal',
 116   );
 117
 118 This role provides an animal attribute, but requires that the consumer
 119 of the role provide a builder method it.
 120
 121   package CatLover;
 122   use Moose;
 123
 124   with 'HasAnimal';
 125
 126   sub _build_animal {
 127       return Cat->new();
 128   }
 129
 130 =head2 The lazy_build shortcut
 131
 132 The C<lazy_build> attribute parameter can be used as sugar to specify
 133 a whole bunch of options at once.
 134
 135   has 'animal' => (
 136       is         => 'ro',
 137       isa        => 'Animal',
 138       lazy_build => 1,
 139   );
 140
 141 This is a shorthand for this:
 142
 143   has 'animal' => (
 144       is        => 'ro',
 145       isa       => 'Animal',
 146       required  => 1,
 147       lazy      => 1,
 148       builder   => '_build_animal',
 149       predicate => 'has_animal',
 150       clearer   => 'clear_animal',
 151   );
 152
 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.
 158
 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
 162 C<_build__animal>.
 163
 164 =head1 CONCLUSION
 165
 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
 170 definition.
 171
 172 Here are some good rules for determining when to use C<builder> vs
 173 C<default>.
 174
 175 If the default value is a simple scalar that only needs to be
 176 calculated once (or a constant), use C<default>.
 177
 178 If the default value is an empty reference that needs to be wrapped in
 179 a coderef like C<sub { [] }>, use C<default>.
 180
 181 Otherwise, use C<builder>.
 182
 183 This ensures that your classes are easily subclassable, and also helps
 184 keep crufty code out of your attribute definition blocks.
 185
 186 =head1 AUTHOR
 187
 188 Dave Rolsky E<lt>autarch@urth.orgE<gt>
 189
 190 =head1 COPYRIGHT AND LICENSE
 191
 192 Copyright 2006-2008 by Infinity Interactive, Inc.
 193
 194 L<http://www.iinteractive.com>
 195
 196 This library is free software; you can redistribute it and/or modify
 197 it under the same terms as Perl itself.
 198
 199 =cut