NAME
DBIx::Tree::MaterializedPath::PathMapper - manipulates paths for "materialized path" trees
VERSION
Version 0.04
SYNOPSIS
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"DESCRIPTION
This module manipulates path representations for DBIx::Tree::MaterializedPath "materialized path" trees.
PATH REPRESENTATIONS
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.
LIMITATIONS
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.
METHODS
new
$mapper = DBIx::Tree::MaterializedPath::PathMapper->new()Returns a path mapping object.
is_root
$mapper->is_root( $path )Given a path, returns true if the path represents the root node.
depth
$mapper->depth( $path )Given a path, returns the depth of the node in the tree. The root node is at zero depth.
map
$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.
unmap
$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").
parent_path
$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.
first_child_path
$mapper->first_child_path( $path )Given a path to a node, return a path to the first child of that node.
next_child_path
$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.)
Returns an empty string if the input path represents the root node.
where
$mapper->where( $where )Given an SQL::Abstract-styleSQL "where" data structure, return an SQL "where" clause, and the corresponding array of bind params.
child_where
$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.
sibling_where
$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.
sibling_to_the_right_where
$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.
sibling_to_the_left_where
$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.
descendants_where_struct
$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.
descendants_where
$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.
descendants_and_self_where
$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.
parent_where
$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.
is_ancestor_of
$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.
is_descendant_of
$mapper->is_descendant_of( $path1, $path2 )Return true if path1 represents a descendant of path2.
Returns false if path1 and path2 represent the same node.
SEE ALSO
DBIx::Tree::MaterializedPath::Node
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::PathMapperYou 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
CPAN Ratings
Search CPAN
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.