.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "DBIx::Class::Tree::AdjacencyList 3pm"
.TH DBIx::Class::Tree::AdjacencyList 3pm "2023-02-14" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
DBIx::Class::Tree::AdjacencyList \- Manage a tree of data using the common adjacency list model.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Create a table for your tree data.
.PP
.Vb 5
\&  CREATE TABLE employees (
\&    employee_id INTEGER PRIMARY KEY AUTOINCREMENT,
\&    parent_id INTEGER NOT NULL DEFAULT 0,
\&    name TEXT NOT NULL
\&  );
.Ve
.PP
In your Schema or \s-1DB\s0 class add Tree::AdjacencyList to the top
of the component list.
.PP
.Vb 1
\&  _\|_PACKAGE_\|_\->load_components(qw( Tree::AdjacencyList ... ));
.Ve
.PP
Specify the column that contains the parent \s-1ID\s0 of each row.
.PP
.Vb 2
\&  package My::Employee;
\&  _\|_PACKAGE_\|_\->parent_column(\*(Aqparent_id\*(Aq);
.Ve
.PP
Optionally, automatically maintane a consistent tree structure.
.PP
.Vb 1
\&  _\|_PACKAGE_\|_\->repair_tree( 1 );
.Ve
.PP
That's it, now you can modify and analyze the tree.
.PP
.Vb 2
\&  #!/usr/bin/perl
\&  use My::Employee;
\&
\&  my $employee = My::Employee\->create({ name=>\*(AqMatt S. Trout\*(Aq });
\&
\&  my $rs = $employee\->children();
\&  my @siblings = $employee\->children();
\&
\&  my $parent = $employee\->parent();
\&  $employee\->parent( 7 );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
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 \s-1ID\s0 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 \s-1ID\s0 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.
.SH "METHODS"
.IX Header "METHODS"
.SS "parent_column"
.IX Subsection "parent_column"
.Vb 1
\&  _\|_PACKAGE_\|_\->parent_column(\*(Aqparent_id\*(Aq);
.Ve
.PP
Declares the name of the column that contains the self-referential
\&\s-1ID\s0 which defines the parent row.  This will create a has_many (children) 
and belongs_to (parent) relationship.
.PP
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 \s-1DAG.\s0
.SS "repair_tree"
.IX Subsection "repair_tree"
.Vb 1
\&  _\|_PACKAGE_\|_\->repair_tree( 1 );
.Ve
.PP
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.
.PP
So, for example, if the tree is like this:
.PP
.Vb 6
\&  A
\&    B
\&      C
\&      D
\&        E
\&    F
.Ve
.PP
And you execute:
.PP
.Vb 1
\&  $b\->parent( $d );
.Ve
.PP
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.
.PP
.Vb 6
\&  A
\&    C
\&    D
\&      B
\&      E
\&    F
.Ve
.SS "parent"
.IX Subsection "parent"
.Vb 3
\&  my $parent = $employee\->parent();
\&  $employee\->parent( $parent_obj );
\&  $employee\->parent( $parent_id );
.Ve
.PP
Retrieves the object's parent object, or changes the object's
parent to the specified parent or parent \s-1ID.\s0  If you would like
to make the object the root node, just set the parent to 0.
.PP
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.
.SS "ancestors"
.IX Subsection "ancestors"
.Vb 1
\&  @list = $employee\->ancestors();
.Ve
.PP
Returns a list of ancestors starting with a record's
parent and moving toward the tree root.
.SS "has_descendant"
.IX Subsection "has_descendant"
.Vb 1
\&  if ($employee\->has_descendant( $id )) { ... }
.Ve
.PP
Returns true if the object has a descendant with the
specified \s-1ID.\s0
.SS "parents"
.IX Subsection "parents"
.Vb 2
\&  my $parents = $node\->parents();
\&  my @parents = $node\->parents();
.Ve
.PP
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 \s-1DAG.\s0
.SS "children"
.IX Subsection "children"
.Vb 2
\&  my $children_rs = $employee\->children();
\&  my @children = $employee\->children();
.Ve
.PP
Returns a list or record set, depending on context, of all
the objects one level below the current one.  This method
is created when \fBparent_column()\fR is called, which sets up a
has_many relationship called children.
.SS "attach_child"
.IX Subsection "attach_child"
.Vb 2
\&  $parent\->attach_child( $child );
\&  $parent\->attach_child( $child, $child, ... );
.Ve
.PP
Sets the child, or children, to the new parent.  Returns 1
on success and returns 0 if the parent object already has
the child.
.SS "siblings"
.IX Subsection "siblings"
.Vb 2
\&  my $rs = $node\->siblings();
\&  my @siblings = $node\->siblings();
.Ve
.PP
Returns either a result set or an array of all other objects
with the same parent as the calling object.
.SS "attach_sibling"
.IX Subsection "attach_sibling"
.Vb 2
\&  $obj\->attach_sibling( $sibling );
\&  $obj\->attach_sibling( $sibling, $sibling, ... );
.Ve
.PP
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.
.SS "is_leaf"
.IX Subsection "is_leaf"
.Vb 1
\&  if ($obj\->is_leaf()) { ... }
.Ve
.PP
Returns 1 if the object has no children, and 0 otherwise.
.SS "is_root"
.IX Subsection "is_root"
.Vb 1
\&  if ($obj\->is_root()) { ... }
.Ve
.PP
Returns 1 if the object has no parent, and 0 otherwise.
.SS "is_branch"
.IX Subsection "is_branch"
.Vb 1
\&  if ($obj\->is_branch()) { ... }
.Ve
.PP
Returns 1 if the object has a parent and has children.
Returns 0 otherwise.
.SS "set_primary_key"
.IX Subsection "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.
.SH "INHERITED METHODS"
.IX Header "INHERITED METHODS"
.SS "DBIx::Class"
.IX Subsection "DBIx::Class"
.IP "\(bu" 4
mk_classdata
.IP "\(bu" 4
component_base_class
.SS "DBIx::Class::Componentised"
.IX Subsection "DBIx::Class::Componentised"
.IP "\(bu" 4
inject_base
.IP "\(bu" 4
load_components
.IP "\(bu" 4
load_own_components
.SS "Class::Data::Accessor"
.IX Subsection "Class::Data::Accessor"
.IP "\(bu" 4
mk_classaccessor
.SH "AUTHOR"
.IX Header "AUTHOR"
Aran Clary Deltac <bluefeet@cpan.org>
.SH "LICENSE"
.IX Header "LICENSE"
You may distribute this code under the same terms as Perl itself.