Moose::...Features(3)

🌸 Moose::...Features(3) — bestie edition 💖

okay so this is a page from the User Contributed Perl Documentation (the manual name, yes it's giving very "the group chat has a wiki"), and it's literally titled Moose::Cookbook::Basics::BinaryTree_AttributeFeatures. We're cooking today. 🍓

---

✨ NAME ✨

Moose::Cookbook::Basics::BinaryTree_AttributeFeatures — it demonstrates various attribute features including lazy, predicates, weak refs, and more. yeah. the whole buffet. 👑

---

🎀 VERSION 🎀

version 2.4000. that's the one, babes. 💅

---

🦋 SYNOPSIS 🦋

here's the whole class, no edits, no cap:

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. and like, specifically, we're introducing a bunch of new attribute options: predicate, lazy, and trigger. the trio. the moment. 🔥

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. a whole little family tree, literally. 🌳

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. anything!! it's giving "no rules, just vibes" but for types.

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. it's a lil note to your future self and your coworkers. 🫶

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. cute, right? ✨

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. so you can just ask. respectfully. 💅

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. memory leaks? not on our watch bestie. 🚫💧

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) so like. don't. 😭

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. shared?? like one single water bottle for the whole class?? 🙈

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. 💀 for real, do not.

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. iykyk.

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! 💥 infinite recursion said "not me being the main character".

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. lazy queen behavior, honestly. 👑

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. important distinction bestie, write it down. 📝

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. (yes, the original says "that is has" — we're keeping it, no notes. 💖)

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. go off, build something iconic. 🫶

---

🧚 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 :) — the smiley is load-bearing. 🙈

• (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@cpan.org>
• Dave Rolsky <autarch@urth.org>
• Jesse Luehrs <doy@cpan.org>
• Shawn M Moore <sartak@cpan.org>
• יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
• Karen Etheridge <ether@cpan.org>
• Florian Ragwitz <rafl@debian.org>
• Hans Dieter Pearcey <hdp@cpan.org>
• Chris Prather <chris@prather.org>
• Matt S Trout <mstrout@cpan.org>

the whole squad, assembled. 🔥

---

💅 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. slay, open source. 🌈

---

okay that's the whole page!! 🎀 this was rendered by perl v5.42.0, dated 2025-07-25, and it's part of the User Contributed Perl Documentation — so if you ever need it again, that's your receipt. bye bestie, go write a binary tree 💖🦋✨