/ 
DBIx-Tree-Persist-1.04
River stage zero No dependents
/ DBIx::Tree::Persist

NAME

DBIx::Tree::Persist - Play with Tree and Tree::Persist a la DBIx::Tree

Synopsis

First, edit lib/DBIx/Tree/Persist/.htdbix.tree.persist.conf.

Then run the scripts in this order (see scripts/test.sh):

scripts/drop.tables.pl

Drop tables one and two.

Of course, you only run this after running create.tables.pl.

scripts/create.tables.pl

Create tables one and two.

Some notes regarding the ways tables one and two are declared (in DBIx::Tree::Persist::Create):

Null 'v' Not Null

parent_id is not 'not null', because Tree::Persist stores a null as the parent of the root.

Foreign Keys

If parent_id is 'references two(id)', then it cannot be set to 0 for the root, because id 0 does not exist.

However, by omitting 'references two(id)', the parent_id of the root can be (manually) set to 0, and Tree::Persist still reads in the tree properly.

scripts/populate.tables.pl

Populate table two from the text file data/two.txt.

The data comes from the docs for DBIx::Tree.

populate.tables.pl uses neither Tree nor Tree::Persist.

The code in DBIx::Tree::Persist::Create uses 0 as the parent_id of the root, whereas Tree::Persist uses null.

This is both to demonstrate the point made above that Tree::Persist handles this, and to adhere to my convention to use 'not null' whenever possible. Clearly, this is not possible when it's Tree::Persist writing to the database. Hence table two which I write can use 'not null', but table one can't use it, since table one is populated by Tree::Persist.

This convention is adopted from:

Joe Celko's SQL for Smarties 2nd edition
Morgan Kaufmann
1-55860-576-2
Section 6.9, page 120, Design Advice for NULLs
scripts/report.tables.pl

Report the record counts from tables one and two.

scripts/tree.pl -t two -v

Traverse and print table two.

This run uses Tree::Persist, and Tree.

scripts/tree.pl -t two -c one

Copy table two to table one.

This run uses Tree::Persist, and Tree.

scripts/tree.pl -t two -c one

Copy table two to table one, again. Table one now contains 2 independent trees.

scripts/tree.pl -t one -s 1 -v

Traverse and print table one, starting from id = 1.

scripts/tree.pl -t one -s 21 -v

Traverse and print table one, starting from id = 21.

The tree structures for the 2 trees printed by the last 2 commands will be the same. However, since the trees are stored at different offsets within table one, the ids associated with each corresponding node will be different.

scripts/tree.pl -t one -d -s 1 -v

Use the -data_structure option to call the build_structure() method, and to output that structure instead of pretty-printing the tree.

Description

DBIx::Tree::Persist provides sample code for playing with Tree and Tree::Persist a la DBIx::Tree.

Distributions

This module is available as a Unix-style distro (*.tgz).

See http://savage.net.au/Perl-modules/html/installing-a-module.html for help on unpacking and installing distros.

Method: build_structure($root)

Returns a Perl data structure which can be turned into JSON.

The -data_structure option to scripts/tree.pl gives you access to this feature.

Method: copy_table()

If copy_name is used to pass a table name to new(), sub run() calls sub copy_table().

If copy_name is not used, sub run() calls sub traverse().

sub copy_table() shows how to build a tree based on a linear scan of a dataset.

Method: new()

See scripts/tree.pl for how to pass sample parameters to new() via a command-line program.

new() takes a hash of parameters:

copy_name => 'A table name'

copy_name is optional.

If specified, the code copies the data from the table named with the -t option to the table named with the -c option.

dbh => $dbh

dbh is optional.

If specified, the code uses the $dbh provided.

If not specified, the code reads the config file lib/DBIx/Tree/Persist/.htdbix.tree.persist.conf to get parameters and calls DBI -> connect() to generate a dbh.

This is mainly used for testing. See t/test.t.

starting_id => N

starting_id is optional.

If specified, a tree is read from the table named with the -t option, starting at the id given here.

If not specified, starting_id defaults to 1.

table_name => 'A table name'

table_name is mandatory.

The table named with the -t option is always used as input.

It will (probably) have been populated with scripts/populate.tables.pl.

verbose => N

verbose is optional.

If specified and > 0, if provides more progress reports.

If not specified, it defaults to 0, which minimizes output.

Method: pretty_print($root)

Print the tree nicely. This method is called from traverse() if the -data_structure option is not used.

Method: run()

After calling new(...), you have to call run(). See scripts/tree.pl for sample code.

Method: traverse()

If copy_name is used to pass a table name to new(), sub run() calls sub copy_table().

If copy_name is not used, sub run() calls sub traverse().

sub traverse() shows how to build a tree from a disk file, and to then process that tree.

if the -data_structure option (to scripts/tree.pl) is used, the tree is converted to a data structure, which is then printed using the Dumper() method of Data::Dumper::Concise.

If the -data_structure option is not used, the tree is pretty-printed by calling the method pretty_print().

Support

Email the author, or log a bug on RT:

https://rt.cpan.org/Public/Dist/Display.html?Name=DBIx-Tree-Persist.

See Also

Data::NestedSet. This module has its own list of See Also references.

DBIx::Tree::NestedSet. This module has its own list of See Also references.

DBIx::Tree.

Tree.

Tree::Persist.

Tree::DAG_Node.

Tree::DAG_Node::Persist.

Author

DBIx::Tree::Persist was written by Ron Savage <ron@savage.net.au> in 2010.

Home page: http://savage.net.au/index.html.

Copyright

Australian copyright (c) 2010, Ron Savage.

All Programs of mine are 'OSI Certified Open Source Software'; you can redistribute them and/or modify them under the terms of The Artistic License, a copy of which is available at: http://www.opensource.org/licenses/index.html.