Moose::Cookbook::Basics::BinaryTree_AttributeFeatures - phpMan

NAME
    Moose::Cookbook::Basics::BinaryTree_AttributeFeatures - Demonstrates
    various attribute features including lazy, predicates, weak refs, and
    more

VERSION
    version 2.2200

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] ) },
          trigger   => \&_set_parent_for_child
      );

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

      sub _set_parent_for_child {
          my ( $self, $child ) = @_;

          confess "You cannot insert a tree which already has a parent"
              if $child->has_parent;

          $child->parent($self);
      }

DESCRIPTION
    This recipe shows how various advanced attribute features can be used to
    create complex and powerful behaviors. In particular, we introduce a
    number of new attribute options, including "predicate", "lazy", and
    "trigger".

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

    Let's take a look at the "node" attribute:

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

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

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

    Next, let's move on to the "parent" attribute:

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

    Again, we have a read-write accessor. This time, the "isa" option says
    that this attribute must always be an instance of "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 "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 "has_parent".

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

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

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

    There are three new options here, "lazy", "default", and "trigger". The
    "lazy" and "default" options are linked. In fact, you cannot have a
    "lazy" attribute unless it has a "default" (or a "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 BankAccount's "balance" attribute had a default
    value of 0. Given a non-reference, Perl copies the *value*. However,
    given a reference, it does not do a deep clone, instead simply copying
    the reference. If you just specified a simple 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.

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

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

    You'll notice that we use $_[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 "BinaryTree" object in our default, with
    the current tree as the parent.

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

    By making our "left" and "right" attributes "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 "right"
    and "left" accessors are not quite correct. When one of these is set, we
    want to make sure that we update the parent of the "left" or "right"
    attribute's tree.

    We could write our own accessors, but then why use Moose at all?
    Instead, we use a "trigger". A "trigger" accepts a subroutine reference,
    which will be called as a method whenever the attribute is set. This can
    happen both during object construction or later by passing a new object
    to the attribute's accessor method. However, it is not called when a
    value is provided by a "default" or "builder".

      sub _set_parent_for_child {
          my ( $self, $child ) = @_;

          confess "You cannot insert a tree which already has a parent"
              if $child->has_parent;

          $child->parent($self);
      }

    This trigger does two things. First, it ensures that the new child node
    does not already have a parent. This is done for the sake of simplifying
    the example. If we wanted to be more clever, we would remove the child
    from its old parent tree and add it to the new one.

    If the child has no parent, we will add it to the current tree, and we
    ensure that is has the correct value for its "parent" attribute.

    As with all the other recipes, BinaryTree can be used just like any
    other Perl 5 class. A more detailed example of its usage can be found in
    t/recipes/basics_binarytree_attributefeatures.t.

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.

FOOTNOTES
    (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 :)

    (2) You *can* use the "default" option without the "lazy" option if you
        like, as we showed in the second recipe.

        Also, you can use "builder" instead of "default". See
        Moose::Cookbook::Basics::BinaryTree_BuilderAndLazyBuild for details.

AUTHORS
    *   Stevan Little <stevan AT cpan.org>

    *   Dave Rolsky <autarch AT urth.org>

    *   Jesse Luehrs <doy AT cpan.org>

    *   Shawn M Moore <sartak AT cpan.org>

    *   יובל קוג'מן (Yuval Kogman) <nothingmuch AT woobling.org>

    *   Karen Etheridge <ether AT cpan.org>

    *   Florian Ragwitz <rafl AT debian.org>

    *   Hans Dieter Pearcey <hdp AT cpan.org>

    *   Chris Prather <chris AT prather.org>

    *   Matt S Trout <mstrout AT cpan.org>

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.