- NAME
- SYNOPSIS
- DESCRIPTION

- new - Create a Rebuild object

- COPYRIGHT
- VERSION

# NAME

GT::SQL::Tree::Rebuild - Helps to turn a table into one usable by GT::SQL::Tree.

# SYNOPSIS

        use GT::SQL::Tree;
        use GT::SQL::Tree::Rebuild;

        my $rebuild = GT::SQL::Tree::Rebuild->new(
            table => $DB->table('MyTable'),
            missing_root => \&root_code,
            missing_father => \&father_code,
            missing_depth => \&depth_code,
            order_by => 'column_name'
        );

        $DB->editor('MyTable')->add_tree(root => $root_col, father => $father_col, depth => $depth_col, rebuild => $rebuild);

# DESCRIPTION

GT::SQL::Tree::Rebuild is designed to go hand-in-hand with GT::SQL::Tree and aids in turning an existing table into one with the neccessary root, father and depth columns needed by GT::SQL::Tree.

The main purpose is to do a one-shot conversion of a table to make it compatible with GT::SQL::Tree.

## new - Create a Rebuild object

There is only one method that is called - new. You pass the arguments needed and get back a GT::SQL::Tree::Rebuild object. This object should then be passed into GT::SQL::Tree->create (typically via `$editor->add_tree()`)

`new()` takes a hash with up to 4 argument pairs: ``table'' (required), and one or more of ``missing_root'', ``missing_father'', or ``missing_depth''. The values are explained below.

table

  Required. You specify the table object for the table to rebuild. For example, if you are going to add a tree to the ``Category'' table, you provide the ``Category'' table object here.

cols

  By default, an entire row will be returned. To speed up the process and lower the memory usage, you can use the `cols` option, which specifies the columns to select for $row. It is recommended that you only select columns that you need as doing so will definately save time and memory.

missing_father, missing_root, missing_depth

  Each of these arguments takes a code reference as its value. The arguments to the code references are as follows:

$row

  The first argument is a hash reference of the row being examined. Your job, in the code reference, is to examine $row and determine the missing value, depending on which code reference is being called. missing_root needs to return the root_id for this row; missing_father needs to return the father_id, and the missing_depth code reference should return the depth for the row.

$table

  The second argument passed to the code references is the same table object that you pass into new(), which you can select from if neccessary.

missing_father

  The `missing_father` code reference is called first - before `missing_root` and `missing_depth`. The code reference is called as described above and should return the ID of the father of the row passed in. A false return (0 or undef) is interpreted as meaning that this is a root and therefore has no father.

missing_root

  `missing_root` has to return the root of the row passed in. This is called after `missing_father`, so the $row will contain whatever you returned in `missing_father` in the father ID column. Of course, this only applies if using both `missing_root` and `missing_father`.

missing_depth

  `missing_depth` has to return the depth of the row passed in. This is called last, so if you are also using `missing_father` and/or `missing_root`, you will have whatever was returned by those code refs available in the $row.

order_by

  The query done to retrieve records can be sorted using the `order_by` option. It should be anything valid for ``ORDER BY _____''. Often it can be useful to have your results returned in a certain order - for example: order_by => 'depth_column ASC' would insure that parents come before roots. Of course, this example wouldn't work if you are using ``missing_depth'' since none of the depth values will be set.

Once you have a GT::SQL::Tree::Rebuild object, you should pass it into `GT::SQL::Tree->create` (which typically involves passing it into `$editor->add_tree()`, which passed it through). Before calculating the tree, GT::SQL::Tree will call on the rebuild object to reproduce the father, root, and/or depth columns (whichever you specified).

# COPYRIGHT

Copyright (c) 2004 Gossamer Threads Inc. All Rights Reserved. http://www.gossamer-threads.com/

# VERSION

Revision: $Id: Rebuild.pm,v 1.10 2005/04/06 23:11:08 jagerman Exp $