DBIx::Tree::MaterializedPath::PathMapper - manipulates paths for "materialized path" trees
Version 0.06
use DBIx::Tree::MaterializedPath::PathMapper; my $mapper = DBIx::Tree::MaterializedPath::PathMapper->new(); # Path to the 2nd child of the 3rd child of the root node: my $path_in_db = $mapper->map('1.3.2'); my $path = $mapper->unmap($path_in_db); # "1.3.2"
This module manipulates path representations for DBIx::Tree::MaterializedPath "materialized path" trees.
The "human-readable" path is a sequence of integers separated by periods that represents the path from the root node of the tree to one of it's children.
The first integer (representing the root node) is always a "1". Subsequent integers represent the Nth child node of the parent, e.g. "1.7" would be the 7th child of the root node, and "1.7.2" would be the 2nd child of the 7th child of the root node.
The "human-readable" path for each node is the tree is mapped into a different format for storage in the database. The format used for database storage must meet several criteria in order for tree manipulation via SQL to work:
The human-readable path must map uniquely to the stored path, and vice versa.
The stored path strings should sort such that the nodes they represent would be traversed leftmost depth-first.
The length of each "chunk" of the stored path (where each chunk represents one step deeper into the tree) should be a fixed value. E.g. "1.108.15" could map to something like "001.108.015" if the chunksize was 3. This ensures that the length of the path representation is a function of the depth of the node in the tree.
The stored path may be prefixed with additional info, but there should be no extraneous info at the end. Removing one "chunk" from the end of a node's path should always result in the path for that node's parent.
This implementation uses a default chunksize of 5 when mapping the digits in the human-readable path into a hex representation. This means that the highest numbered child at any level is 0xfffff, or 1,048,575.
In addition to limiting the maximum children a node may have, the chunksize also affects the length of the path strings and thus the amount of database storage required.
The default chunksize may be overridden by passing a "chunksize" option to new, with an integer value ranging from 1 to 8.
new
$mapper = DBIx::Tree::MaterializedPath::PathMapper->new()
Returns a path mapping object.
$mapper->is_root( $path )
Given a path, returns true if the path represents the root node.
$mapper->depth( $path )
Given a path, returns the depth of the node in the tree. The root node is at zero depth.
$mapper->map( $human_readable_path )
Maps a string representing the path from the root node of the tree to a child node from human-readable format (e.g. "1.2.4.1") to the format stored in the database.
$mapper->unmap( $path )
Maps a string representing the path from the root node of the tree to a child node from the format stored in the database to human-readable format (e.g. "1.2.4.1").
$mapper->parent_path( $path )
Given a path to a node, return the path to its immediate parent.
Returns an empty string if the input path represents the root node.
$mapper->first_child_path( $path )
Given a path to a node, return a path to the first child of that node.
$mapper->next_child_path( $path, $optional_n )
Given a path to a child node, return a path to the next child for the same parent.
If $n is specified, return the path to the nth next child. ($n effectively defaults to 1.)
$mapper->where( $where )
Given an SQL::Abstract-styleSQL "where" data structure, return an SQL "where" clause, and the corresponding array of bind params.
$mapper->child_where( $path_column_name, $path )
Given the name of the path column and a path to a node, return an SQL "where" clause suitable for finding the node's direct children, and the corresponding array of bind params.
$mapper->sibling_where( $path_column_name, $path )
Given the name of the path column and a path to a node, return an SQL "where" clause suitable for finding the node's siblings, and the corresponding array of bind params.
$mapper->sibling_to_the_right_where( $path_column_name, $path )
Given the name of the path column and a path to a node, return an SQL "where" clause suitable for finding siblings to the right of the node, and the corresponding array of bind params.
$mapper->sibling_to_the_left_where( $path_column_name, $path )
Given the name of the path column and a path to a node, return an SQL "where" clause suitable for finding siblings to the left of the node, and the corresponding array of bind params.
$mapper->descendants_where_struct( $path_column_name, $path )
Given the name of the path column and a path to a node, return an SQL::Abstract-styleSQL "where" data structure suitable for finding all of the node's descendants.
$mapper->descendants_where( $path_column_name, $path )
Given the name of the path column and a path to a node, return an SQL "where" clause suitable for finding all of the node's descendants, and the corresponding array of bind params.
$mapper->descendants_and_self_where( $path_column_name, $path )
Given the name of the path column and a path to a node, return an SQL "where" clause suitable for finding a node and all of its descendants, and the corresponding array of bind params.
$mapper->parent_where( $path_column_name, $path )
Given the name of the path column and a path to a node, return an SQL "where" clause suitable for finding the node's parent, and the corresponding array of bind params.
$mapper->is_ancestor_of( $path1, $path2 )
Return true if path1 represents an ancestor of path2.
Returns false if path1 and path2 represent the same node.
$mapper->is_descendant_of( $path1, $path2 )
Return true if path1 represents a descendant of path2.
DBIx::Tree::MaterializedPath
DBIx::Tree::MaterializedPath::Node
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.
bug-dbix-tree-materializedpath at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc DBIx::Tree::MaterializedPath::PathMapper
You can also look for information at:
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=DBIx-Tree-MaterializedPath
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/DBIx-Tree-MaterializedPath
CPAN Ratings
http://cpanratings.perl.org/d/DBIx-Tree-MaterializedPath
Search CPAN
http://search.cpan.org/dist/DBIx-Tree-MaterializedPath
Larry Leszczynski, <larryl at cpan.org>
<larryl at cpan.org>
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.
To install DBIx::Tree::MaterializedPath, copy and paste the appropriate command in to your terminal.
cpanm
cpanm DBIx::Tree::MaterializedPath
CPAN shell
perl -MCPAN -e shell install DBIx::Tree::MaterializedPath
For more information on module installation, please visit the detailed CPAN module installation guide.