Larry Leszczynski > DBIx-Tree-MaterializedPath-v0.06 > DBIx::Tree::MaterializedPath::PathMapper

Download:
DBIx-Tree-MaterializedPath-v0.06.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  1
Open  0
View/Report Bugs
Module Version: v0.06   Source  

NAME ^

DBIx::Tree::MaterializedPath::PathMapper - manipulates paths for "materialized path" trees

VERSION ^

Version 0.06

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:

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

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::PathMapper

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.

syntax highlighting: