DBIx::Class::Tree::AdjacencyList - Manage a tree of data using the common adjacency list model.

       Aran Clary Deltac <bluefeet@cpan.org>

       This module provides methods for working with adjacency lists.  The adjacency list model is a very common
       way of representing a tree structure.  In this model each row in a table has a prent ID column that
       references the primary key of another row in the same table.  Because of this the primary key must only
       be one column and is usually some sort of integer.  The row with a parent ID of 0 is the root node and is
       usually the parent of all other rows.  Although, there is no limitation in this module that would stop
       you from having multiple root nodes.

DBIx::Class
       •   mk_classdata

       •   component_base_class

   DBIx::Class::Componentised
       •   inject_base

       •   load_components

       •   load_own_components

   Class::Data::Accessor
       •   mk_classaccessor

       You may distribute this code under the same terms as Perl itself.

perl v5.36.0                                       2023-02-14              DBIx::Class::Tree::AdjacencyList(3pm)

parent_column
         __PACKAGE__->parent_column('parent_id');

       Declares the name of the column that contains the self-referential ID which defines the parent row.  This
       will create a has_many (children) and belongs_to (parent) relationship.

       This method also sets up an additional has_many relationship called parents which is useful when you want
       to treat an adjacency list as a DAG.

   repair_tree
         __PACKAGE__->repair_tree( 1 );

       When set a true value this flag causes all changes to a node's parent to trigger an integrity check on
       the tree.  If, when changing a node's parent to one of it's descendents then all its children will first
       be moved to have the same current parent, and then the node's parent is changed.

       So, for example, if the tree is like this:

         A
           B
             C
             D
               E
           F

       And you execute:

         $b->parent( $d );

       Since D is a descendant of B then all of D's siblings get their parent changed to A.  Then B's parent is
       set to D.

         A
           C
           D
             B
             E
           F

   parent
         my $parent = $employee->parent();
         $employee->parent( $parent_obj );
         $employee->parent( $parent_id );

       Retrieves the object's parent object, or changes the object's parent to the specified parent or parent
       ID.  If you would like to make the object the root node, just set the parent to 0.

       If you are setting the parent then 0 will be returned if the specified parent is already the object's
       parent and 1 on success.

   ancestors
         @list = $employee->ancestors();

       Returns a list of ancestors starting with a record's parent and moving toward the tree root.

   has_descendant
         if ($employee->has_descendant( $id )) { ... }

       Returns true if the object has a descendant with the specified ID.

   parents
         my $parents = $node->parents();
         my @parents = $node->parents();

       This has_many relationship is not that useful as it will never return more than one parent due to the
       one-to-many structure of adjacency lists.  The reason this relationship is defined is so that this tree
       type may be treated as if it was a DAG.

   children
         my $children_rs = $employee->children();
         my @children = $employee->children();

       Returns a list or record set, depending on context, of all the objects one level below the current one.
       This method is created when parent_column() is called, which sets up a has_many relationship called
       children.

   attach_child
         $parent->attach_child( $child );
         $parent->attach_child( $child, $child, ... );

       Sets the child, or children, to the new parent.  Returns 1 on success and returns 0 if the parent object
       already has the child.

   siblings
         my $rs = $node->siblings();
         my @siblings = $node->siblings();

       Returns either a result set or an array of all other objects with the same parent as the calling object.

   attach_sibling
         $obj->attach_sibling( $sibling );
         $obj->attach_sibling( $sibling, $sibling, ... );

       Sets the passed in object(s) to have the same parent as the calling object.  Returns 1 on success and 0
       if the sibling already has the same parent.

   is_leaf
         if ($obj->is_leaf()) { ... }

       Returns 1 if the object has no children, and 0 otherwise.

   is_root
         if ($obj->is_root()) { ... }

       Returns 1 if the object has no parent, and 0 otherwise.

   is_branch
         if ($obj->is_branch()) { ... }

       Returns 1 if the object has a parent and has children.  Returns 0 otherwise.

   set_primary_key
       This method is an override of DBIx::Class' method for setting the class' primary key column(s).  This
       method passes control right on to the normal method after first validating that only one column is being
       selected as a primary key.  If more than one column is then an error will be thrown.

       DBIx::Class::Tree::AdjacencyList - Manage a tree of data using the common adjacency list model.

       Create a table for your tree data.

         CREATE TABLE employees (
           employee_id INTEGER PRIMARY KEY AUTOINCREMENT,
           parent_id INTEGER NOT NULL DEFAULT 0,
           name TEXT NOT NULL
         );

       In your Schema or DB class add Tree::AdjacencyList to the top of the component list.

         __PACKAGE__->load_components(qw( Tree::AdjacencyList ... ));

       Specify the column that contains the parent ID of each row.

         package My::Employee;
         __PACKAGE__->parent_column('parent_id');

       Optionally, automatically maintane a consistent tree structure.

         __PACKAGE__->repair_tree( 1 );

       That's it, now you can modify and analyze the tree.

         #!/usr/bin/perl
         use My::Employee;

         my $employee = My::Employee->create({ name=>'Matt S. Trout' });

         my $rs = $employee->children();
         my @siblings = $employee->children();

         my $parent = $employee->parent();
         $employee->parent( 7 );