[Bast-commits] r4655 - DBIx-Class-Tree-NestedSet/lib/DBIx/Class/Tree/NestedSet

[rafl at dev.catalyst.perl.org]

Author: rafl
Date: 2008-07-26 01:34:44 +0100 (Sat, 26 Jul 2008)
New Revision: 4655

Modified:
   DBIx-Class-Tree-NestedSet/lib/DBIx/Class/Tree/NestedSet/Multi.pm
Log:
Add some docs.

Modified: DBIx-Class-Tree-NestedSet/lib/DBIx/Class/Tree/NestedSet/Multi.pm
===================================================================
--- DBIx-Class-Tree-NestedSet/lib/DBIx/Class/Tree/NestedSet/Multi.pm	2008-07-25 23:22:49 UTC (rev 4654)
+++ DBIx-Class-Tree-NestedSet/lib/DBIx/Class/Tree/NestedSet/Multi.pm	2008-07-26 00:34:44 UTC (rev 4655)
@@ -6,11 +6,99 @@
 use Carp qw/croak/;
 use parent 'DBIx::Class';
 
+=head1 NAME
+
+DBIx::Class::Tree::NestedSet::Multi - Manage trees of data using the nested set model
+
+=head1 SYNOPSIS
+
+In your result class:
+
+  __PACKAGE__->load_components(qw/Tree::NestedSet::Multi .../);
+
+  __PACKAGE__->tree_columns({
+      left_column  => 'lft',
+      right_column => 'rgt',
+      root_column  => 'top',
+  });
+
+Using it:
+
+  my $root  = My::Tree->create({ ... });
+  my $child = $root->add_to_children({ ... });
+
+  my $rs       = $root->children;
+  my @children = $root->children;
+
+  my $parent  = $child->parent;
+  my $rs      = $child->parents;
+  my @parents = $child->parents;
+
+=head1 DESCRIPTION
+
+This module provides methods for working with nested set trees. The nested tree
+model is a way of representing tree structures.
+
+=cut
+
 our $VERSION = '0.01_01';
 $VERSION = eval $VERSION;
 
 __PACKAGE__->mk_classdata( _tree_columns => {} );
 
+=head1 METHODS
+
+=head2 tree_columns
+
+  __PACKAGE__->tree_columns({
+      left_column  => 'lft',
+      right_column => 'rgt',
+      root_column  => 'root',
+  });
+
+Declare the name of columns and relations to be used. C<left_column>,
+C<right_column> and C<root_column> are required.
+
+The following options exist:
+
+=over 4
+
+=item left_column
+
+Name of the column to use as the left side.
+
+=item right_column
+
+Name of the column to use as the right side.
+
+=item root_column
+
+Name of the column to use to distinguish different trees.
+
+=item root_rel
+
+Name of the relation to the root of the tree. Defaults to C<root>.
+
+=item nodes_rel
+
+Name of the relation to all nodes of the tree. Defaults to C<nodes>.
+
+=item children_rel
+
+Name of the relation to all children of a node. Defaults to C<children>.
+
+=item parents_rel
+
+Name of the relation to all parents of a node. Defaults to C<parents>.
+
+=item parent_rel
+
+Name of the relation to the direct parent of a node. Defaults to C<parent>.
+
+=back
+
+=cut
+
 sub tree_columns {
     my ($class, $args) = @_;
 
@@ -170,12 +258,28 @@
     *search_related_rs = \&search_related;
 }
 
+=head2 is_root
+
+  $is_root = $node->is_root;
+
+Check if a C<$node> is a root node (i.e. has no parents).
+
+=cut
+
 sub is_root {
     my ($self) = @_;
 
     return $self->get_column( $self->tree_columns->{left_column} ) == 1 ? 1 : 0;
 }
 
+=head2 is_leaf
+
+  $is_leaf = $node->is_leaf;
+
+Check if a C<$node> is a leaf (i.e. has no children).
+
+=cut
+
 sub is_leaf {
     my ($self) = @_;
 
@@ -186,10 +290,80 @@
     return $right - $left == 1 ? 1 : 0;
 }
 
+=head2 is_branch
+
+  $is_branch = $node->is_branch;
+
+Check if a C<$node> is a branch (i.e. has children).
+
+=cut
+
 sub is_branch {
     my ($self) = @_;
 
     return !$self->is_leaf;
 }
 
+=head2 $parent
+
+  $parent_node = $node->parent;
+
+Returns the direct parent of C<$node>. The name of this method can be set using
+C<parent_rel> in L<tree_columns>. It defaults to C<parent>.
+
+This is a shortcut for
+
+  $node->parents->first;
+
+=head1 RELATIONS
+
+This module automatically creates several relationships. The name of those
+relations can be set using the parameters to C<tree_columns>.
+
+=head2 $root
+
+  $root_node = $node->root;
+
+belongs_to relation to the root of C<$node>s tree. The name can be configured using
+C<root_rel>. It defaults to C<root>.
+
+=head2 $children
+
+  $rs       = $node->children;
+  @children = $node->children;
+  $child    = $node->add_to_children(...);
+
+has_many relation to the children of C<$node>. The name can be configured using
+C<children_rel>. It defaults to C<children>.
+
+=head2 $parents
+
+  $rs       = $node->parents;
+  @children = $node->parents;
+
+has_many relation to the parents of C<$node>. The name can be configured using
+C<parents_rel>. It defaults to C<parents>.
+
+=head2 $nodes
+
+  $rs    = $node->nodes;
+  @nodes = $node->nodes;
+
+has_many relation to the other nodes in the tree of C<$node>. The name can be
+configured using C<nodes_rel>. It defaults to C<nodes>.
+
+=cut
+
+=head1 AUTHOR
+
+Florian Ragwitz E<lt>rafl at debian.orgE<gt>
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright (c) 2008, Florian Ragwitz.
+
+This is free software. You may distribute this code under the same terms as Perl itself.
+
+=cut
+
 1;