=pod

=head1 NAME

Moose::Cookbook::Basics::Recipe3 - A lazy B<BinaryTree> example

=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,
      default   => sub { BinaryTree->new( parent => $_[0] ) },
  );

  has 'right' => (
      is        => 'rw',
      isa       => 'BinaryTree',
      predicate => 'has_right',
      lazy      => 1,
      default   => sub { BinaryTree->new( parent => $_[0] ) },
  );

  before 'right', 'left' => sub {
      my ( $self, $tree ) = @_;
      $tree->parent($self) if defined $tree;
  };

=head1 DESCRIPTION

This recipe shows how various advanced attribute features can be used
to create complex and powerful behaviors.

The example class is a classic binary tree. Each node in the tree is
itself an instance of C<BinaryTree>. It has a C<node>, which holds
some arbitrary value. It has C<right> and C<left> attributes, which
refer to its child trees, and a C<parent>.

Let's take a look at the C<node> attribute:

  has 'node' => ( is => 'rw', isa => 'Any' );

Moose generates a read-write accessor for this attribute. The type
constraint is C<Any>, which means literally means it can contain
anything.

We could have left out the C<isa> option, but in this case, we are
including ir for the benefit of other programmers, not the computer.

Next, let's move on to the C<parent> attribute:

  has 'parent' => (
      is        => 'rw',
      isa       => 'BinaryTree',
      predicate => 'has_parent',
      weak_ref  => 1,
  );

Again, we have a read-write accessor. This time, the C<isa> option
says that this attribute must always be an instance of
C<BinaryTree>. In the second recipe, we saw that every time we create
a Moose-based class, we also get a corresponding class type
constraint.

The C<predicate> option is new. It creates a method which can be used
to check whether or not a given attribute has been initialized. In
this case, the method is named C<has_parent>.

This brings us to our last attribute option, C<weak_ref>. Since
C<parent> is a circular reference (the tree in C<parent> should
already have a reference to this one, in its C<left> or C<right>
attribute), we want to make sure that we weaken the reference to avoid
memory leaks. If C<weak_ref> is true, it alters the accessor function
so that the reference is weakened when it is set.

Finally, we have the the C<left> and C<right> attributes. They are
essentially identical except for their names, so we'll just look at
C<left>:

  has 'left' => (
      is        => 'rw',
      isa       => 'BinaryTree',
      predicate => 'has_left',
      lazy      => 1,
      default   => sub { BinaryTree->new( parent => $_[0] ) },
  );

There are two new options here, C<lazy> and C<default>. These two
options are linked, and in fact you cannot have a C<lazy> attribute
unless it has a C<default> (or a C<builder>, but we'll cover that
later). If you try to make an attribute lazy without a default, class
creation will fail with an exception. (2)

In the second recipe the B<BankAccount>'s C<balance> attribute had a
default value of C<0>. Given a non-reference, Perl copies the
I<value>. However, given a reference, it does not do a deep clone,
instead simply copying the reference. If you just specified a simply
reference for a default, Perl would create it once and it would be
shared by all objects with that attribute.

As a workaround, we use an anonymous subroutine to generate a new
reference every time the default is called.

  has 'foo' => ( is => 'rw', default => sub { [] } );

In fact, using a non-subroutine reference as a default is illegal in Moose.

  has 'foo' => ( is => 'rw', default => [] );

This will blow up, so don't do it.

You'll notice that we use C<$_[0]> in our default sub. When the
default subroutine is executed, it is called as a method on the
object.

In our case, we're making a new C<BinaryTree> object in our default,
with the current tree as the parent.

Normally, when an object is instantiated, any defaults are evaluted
immediately. With our C<BinaryTree> class, this would be a big
problem! We'd create the first object, which would immediately try to
populate its C<left> and C<right> attributes, which would create a new
C<BinaryTree>, which would populate I<its> C<left> and C<right>
slots. Kaboom!

By making our C<left> and C<right> attributes C<lazy>, we avoid this
problem. If the attribute has a value when it is read, the default is
never executed at all.

We still have one last bit of behavior to add. The autogenerated
C<right> and C<left> accessors are not quite correct. When one of
these is set, we want to make sure that we update the parent of the
C<left> or C<right> attribute's tree.

We could write our own accessors, but then why use Moose at all?
Instead, we use method modifiers:

  before 'right', 'left' => sub {
      my ( $self, $tree ) = @_;
      $tree->parent($self) if defined $tree;
  };

This is a C<before> modifier, just like we saw in the second recipe,
but with two slight differences. First, we are applying the modifier
to more than one method at a time, because both C<left> and C<right>
attributes need the same behavior. The other difference is that we are
not wrapping an inherited method, but rather a method from our own
local class. Wrapping local methods is no different, the only
requirement is that the wrappee must exist before the wrapper is
defined (after all, you cannot wrap something which doesn't exist,
right?).

As with all the other recipes, B<BinaryTree> can be used just like any
other Perl 5 class. A more detailed example of its usage can be found
in F<t/000_recipes/003_recipe.t>.

=head1 CONCLUSION

This recipe introduced several of Moose's advanced features. We hope
that this inspires you to think of other ways these features can be
used to simplify your code.

=head1 FOOTNOTES

=over 4

=item (1)

Weak references are tricky things, and should be used sparingly and
appropriately (such as in the case of circular refs). If you are not
careful, attribute values could disappear "mysteriously" because
Perl's reference counting garbage collector has gone and removed the
item you are weak-referencing.

In short, don't use them unless you know what you are doing :)

=item (2)

You I<can> use the C<default> option without the C<lazy> option if you
like, as we showed in the second recipe.

Also, you can use C<builder> instead of C<default>. See
L<Moose::Cookbook::Basics::Recipe9> for details.

=back

=head1 AUTHORS

Stevan Little E<lt>stevan@iinteractive.comE<gt>

Dave Rolsky E<lt>autarch@urth.orgE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright 2006-2009 by Infinity Interactive, Inc.

L<http://www.iinteractive.com>

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

=cut