Data::Grove(3)

💖 Data::Grove — support for deeply nested structures 💖

okay so bestie, this is Data::Grove, a Perl manpage (that's the 3 in Data::Grove(3) — section 3, library-land ✨), and it's literally the blueprint for deeply nested tree and graph structures. buckle up, it's giving very much "foundation module that other modules are built on" energy. 🎀

✨ SYNOPSIS ✨

use Data::Grove;

$object = MyPackage->new;

package MyPackage;
@ISA = qw{Data::Grove};

🌸 DESCRIPTION 🌸

Data::Grove provides support for deeply nested tree or graph structures. It's intended primarily for Perl module authors — the ones writing modules with, like, many types or classes of objects that need to be manipulated and extended in a consistent and flexible way. 👑

The way you're meant to use Data::Grove: create a core set of "data" classes, then incrementally add functionality to those core data classes using "extension" modules. One reason for this design is so that the data classes can be swapped out and the extension modules can still work with new data sources. fr fr. For example, those other data sources could be disk-based, network-based, or built on top of a relational database. 🦋

Two extension modules that come with Data::Grove are Data::Grove::Parent and Data::Grove::Visitor:

• Data::Grove::Parent adds a "Parent" property to grove objects, and implements a "root" method on grove objects that returns the root node of the tree from anywhere in the tree, plus a "rootpath" method that returns a list of nodes between the root node and "this" node.
• Data::Grove::Visitor adds callback methods "accept" and "accept_name" that call your handler or receiver module back by object type name or by the object's name.

Important vibe check: Data::Grove objects do not contain parent references. Perl garbage collection will delete them when they're no longer referenced, and sub-structures can be shared among several structures. That's the whole point — no parent soup. If you do want parent pointers, Data::Grove::Parent is the one used to create temporary objects with them. 💅

Properties of data classes are accessed directly using Perl's hash functions (i.e. "$object->{Property}"). Extension modules may also define properties that they support or use — for example, Data::Grove::Parent adds "Parent" and "Raw" properties, and Visitor depends on "Name" and "Content" properties. 🍓

See the module XML::Grove for an example implementation of Data::Grove. go look, it slays.

---

👑 METHODS 👑

💜 new( PROPERTIES )

Return a new object blessed into the SubClass, with the given properties. ✨

PROPERTIES may be any of these three things:

• a list of key/value pairs,
• a single hash containing key/value pairs, or
• an existing Data::Grove object.

If an existing Data::Grove is passed to new(), a shallow copy of that object will be returned. And what does shallow copy mean, bestie? It means you get a new object back, but all of the objects underneath still refer to the original objects. so like, new wrapper, same innards. don't get it twisted 😭

🌈 AUTHOR 🌈

Ken MacLeod, ken@bitsko.slc.ut.us 🫶

⭐ SEE ALSO ⭐

perl(1)

---

okay that's the whole page, we ate and left no crumbs 🧚💖 — this was perl v5.42.0, dated 2024-03-04, signing off with main character energy and a little 🎀 for the road.