The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
DBIx-Tree-MaterializedPath-v0.06
River stage zero No dependents
++
/ DBIx::Tree::MaterializedPath::TreeRepresentation

NAME

DBIx::Tree::MaterializedPath::TreeRepresentation - data structure for "materialized path" trees

VERSION

Version 0.06

SYNOPSIS

    # Row data must be sorted by path:
    my $column_names = ['id', 'path', 'name'];
    my $subtree_data = [
                        [ 2, "1.1",     "a"],
                        [ 3, "1.2",     "b"],
                        [ 4, "1.3",     "c"],
                        [ 5, "1.3.1",   "d"],
                        [ 7, "1.3.1.1", "e"],
                        [ 6, "1.3.2",   "f"],
                       ];

    my $subtree_representation =
      DBIx::Tree::MaterializedPath::TreeRepresentation->new($node,
                                                            $column_names,
                                                            $subtree_data);

    $subtree_representation->traverse($coderef, $context);

DESCRIPTION

This module implements a data structure that represents a tree (or subtree) as stored in the database.

Note: Normally these objects would not be created independently - call get_descendants() on a tree or a node to get its descendants as a DBIx::Tree::MaterializedPath::TreeRepresentation object, and then traverse() those descendants.

METHODS

new

    $subtree_data =
      DBIx::Tree::MaterializedPath::TreeRepresentation->new($node,
                                                            $cols_listref,
                                                            $rows_listref,
                                                            $options_hashref);

new() expects a DBIx::Tree::MaterializedPath::Node object (representing the node that this data belongs to), a listref of database column names, and a listref of listrefs, each of which represents a node row in the database.

At minimum, each row must contain entries for the id_column_name and the path_column_name as specified in the DBIx::Tree::MaterializedPath constructor. The rows should be sorted by path in ascending order.

Additionally, the row may contain entries for any metadata columns which are stored with the nodes.

One DBIx::Tree::MaterializedPath::Node object will be created in the data structure for each input row. If the optional parameters hashref contains a true value for "ignore_empty_hash", and if no metadata entries exist in the input row, then the node object's metadata will not be populated, and will only be retrieved from the database when the data() method is called on a given node.

has_nodes

   $subtree_data->has_nodes()

Return true if the data structure contains any nodes.

num_nodes

   $subtree_data->num_nodes()

Return the number of nodes in the data structure.

traverse

    $subtree_data->traverse( $coderef, $optional_context )

Given a coderef, traverse down the data structure in leftmost depth-first order and apply the coderef at each node.

The first argument to the $coderef will be the node being traversed. The second argument to the $coderef will be that node's parent.

If supplied, $context will be the third argument to the coderef. $context can be a reference to a data structure that can allow information to be carried along from node to node while traversing the tree.

E.g. to count the number of descendants:

    my $context = {count => 0};
    my $coderef = sub {
        my ($node, $parent, $context) = @_;
        $context->{count}++;
    };

    my $descendants = $node->get_descendants();
    $descendants->traverse($coderef, $context);

    print "The node has $context->{count} descendants.\n";

Note that you may be able to use closure variables instead of passing them along in $context:

    my $count   = 0;
    my $coderef = sub {
        my ($node, $parent) = @_;
        $count++;
    };

    my $descendants = $node->get_descendants();
    $descendants->traverse($coderef, $context);

    print "The node has $count descendants.\n";

SEE ALSO

DBIx::Tree::MaterializedPath

DBIx::Tree::MaterializedPath::Node

DBIx::Tree::MaterializedPath::PathMapper

BUGS

Please report any bugs or feature requests to bug-dbix-tree-materializedpath at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=DBIx-Tree-MaterializedPath. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc DBIx::Tree::MaterializedPath

You can also look for information at:

AUTHOR

Larry Leszczynski, <larryl at cpan.org>

COPYRIGHT & LICENSE

Copyright 2008 Larry Leszczynski, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.