Add Moose package

CPAN/Moose/Cookbook/Basics/BinaryTree_BuilderAndLazyBuild.pod

@@ -0,0 +1,176 @@
+# PODNAME: Moose::Cookbook::Basics::BinaryTree_BuilderAndLazyBuild
+# ABSTRACT: Builder methods and lazy_build
+
+__END__
+
+=pod
+
+=encoding UTF-8
+
+=head1 NAME
+
+Moose::Cookbook::Basics::BinaryTree_BuilderAndLazyBuild - Builder methods and lazy_build
+
+=head1 VERSION
+
+version 2.2207
+
+=head1 SYNOPSIS
+
+  package BinaryTree;
+  use Moose;
+
+  has 'node' => (is => 'rw', isa => 'Any');
+
+  has 'parent' => (
+      is        => 'rw',
+      isa       => 'BinaryTree',
+      predicate => 'has_parent',
+      weak_ref  => 1,
+  );
+
+  has 'left' => (
+      is        => 'rw',
+      isa       => 'BinaryTree',
+      predicate => 'has_left',
+      lazy      => 1,
+      builder   => '_build_child_tree',
+  );
+
+  has 'right' => (
+      is        => 'rw',
+      isa       => 'BinaryTree',
+      predicate => 'has_right',
+      lazy      => 1,
+      builder   => '_build_child_tree',
+  );
+
+  before 'right', 'left' => sub {
+      my ($self, $tree) = @_;
+      $tree->parent($self) if defined $tree;
+  };
+
+  sub _build_child_tree {
+      my $self = shift;
+
+      return BinaryTree->new( parent => $self );
+  }
+
+=head1 DESCRIPTION
+
+If you've already read
+L<Moose::Cookbook::Basics::BinaryTree_AttributeFeatures>, then this example
+should look very familiar. In fact, all we've done here is replace the
+attribute's C<default> parameter with a C<builder>.
+
+In this particular case, the C<default> and C<builder> options act in
+exactly the same way. When the C<left> or C<right> attribute is read,
+Moose calls the builder method to initialize the attribute.
+
+Note that Moose calls the builder method I<on the object which has the
+attribute>. Here's an example:
+
+  my $tree = BinaryTree->new();
+
+  my $left = $tree->left();
+
+When C<< $tree->left() >> is called, Moose calls C<<
+$tree->_build_child_tree() >> in order to populate the C<left>
+attribute. If we had passed C<left> to the original constructor, the
+builder would not be called.
+
+There are some differences between C<default> and C<builder>. Notably,
+a builder is subclassable, and can be composed from a role. See
+L<Moose::Manual::Attributes> for more details.
+
+=head2 The lazy_build shortcut
+
+The C<lazy_build> attribute option can be used as sugar to specify
+a whole set of attribute options at once:
+
+  has 'animal' => (
+      is         => 'ro',
+      isa        => 'Animal',
+      lazy_build => 1,
+  );
+
+This is a shorthand for:
+
+  has 'animal' => (
+      is        => 'ro',
+      isa       => 'Animal',
+      required  => 1,
+      lazy      => 1,
+      builder   => '_build_animal',
+      predicate => 'has_animal',
+      clearer   => 'clear_animal',
+  );
+
+If your attribute starts with an underscore, Moose is smart and will
+do the right thing with the C<predicate> and C<clearer>, making them
+both start with an underscore. The C<builder> method I<always> starts
+with an underscore.
+
+You can read more about C<lazy_build> in L<Moose::Meta::Attribute>
+
+=head1 CONCLUSION
+
+The C<builder> option is a more OO-friendly version of the C<default>
+functionality. It also separates the default-generating code into a
+well-defined method. Sprinkling your attribute definitions with
+anonymous subroutines can be quite ugly and hard to follow.
+
+=head1 AUTHORS
+
+=over 4
+
+=item *
+
+Stevan Little <stevan@cpan.org>
+
+=item *
+
+Dave Rolsky <autarch@urth.org>
+
+=item *
+
+Jesse Luehrs <doy@cpan.org>
+
+=item *
+
+Shawn M Moore <sartak@cpan.org>
+
+=item *
+
+יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
+
+=item *
+
+Karen Etheridge <ether@cpan.org>
+
+=item *
+
+Florian Ragwitz <rafl@debian.org>
+
+=item *
+
+Hans Dieter Pearcey <hdp@cpan.org>
+
+=item *
+
+Chris Prather <chris@prather.org>
+
+=item *
+
+Matt S Trout <mstrout@cpan.org>
+
+=back
+
+=head1 COPYRIGHT AND LICENSE
+
+This software is copyright (c) 2006 by Infinity Interactive, Inc.
+
+This is free software; you can redistribute it and/or modify it under
+the same terms as the Perl 5 programming language system itself.
+
+=cut