Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Moose::Cookbook::BasicUsereContribuoed:PerlcDocumentatioe_AttributeFeatures(3)

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

VERSION
       version 2.2013

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
       o   Stevan Little <stevan.little@iinteractive.com>

       o   Dave	Rolsky <autarch@urth.org>

       o   Jesse Luehrs	<doy@tozt.net>

       o   Shawn M Moore <code@sartak.org>

       o   xxxx	x<section>xx'xx	(Yuval Kogman) <nothingmuch@woobling.org>

       o   Karen Etheridge <ether@cpan.org>

       o   Florian Ragwitz <rafl@debian.org>

       o   Hans	Dieter Pearcey <hdp@weftsoar.net>

       o   Chris Prather <chris@prather.org>

       o   Matt	S Trout	<mst@shadowcat.co.uk>

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.

perl v5.32.0	      Moose::Cookbook::Basics::BinaryTree_AttributeFeatures(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | CONCLUSION | FOOTNOTES | AUTHORS | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Moose::Cookbook::Basics::BinaryTree_AttributeFeatures&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help