/ 
Tree-Persist-1.14
River stage one • 1 direct dependent • 1 total dependent
/ Tree::Persist

NAME

Tree::Persist - A transparent persistence layer for Tree and its children

SYNOPSIS

Create a tree:

use Tree;
use Tree::Persist;

my($tree_1) = Tree -> new('A') -> add_child
(
	Tree -> new('B'),
	Tree -> new('C') -> add_child
	(
		Tree -> new('D'),
	),
	Tree -> new('E'),
);

Create a datastore, which includes writing the tree:

my($writer) = Tree::Persist -> create_datastore
({
	filename => 't/datafiles/store.xml',
	tree     => $tree_1,
	type     => 'File',
});

Retrieve the tree:

my($reader) = Tree::Persist -> connect
({
	filename => 'scripts/store.xml',
	type     => 'File',
});

my($tree_2) = $reader -> tree;

Or, with a user-specified class name for deflation and inflation:

my($writer) = Tree::Persist -> create_datastore
({
	class    => 'Tree::Persist::File::XMLWithSingleQuotes',
	filename => 't/datafiles/store.xml',
	tree     => $tree_1,
});

my($reader) = Tree::Persist -> connect
({
	class    => 'Tree::Persist::File::XMLWithSingleQuotes',
	filename => 'scripts/store.xml',
});

my($tree_2) = $reader -> tree;

See t/load_from_file.t and t/save_and_load.t for sample code.

General usage of methods:

$store -> autocommit(0);

$tree -> set_value('foo');

DESCRIPTION

This is a transparent persistence layer for Tree and its children. It is fully pluggable and will allow either loading, storing, and/or association with between a datastore and a tree.

NOTE: If you load a subtree, you will have access to the parent id, but the node will be considered the root for the tree you are working with.

PLUGINS

The plugins that have been written are:

Please refer to their documentation for the appropriate options for connect() and create_datastore().

METHODS

Class Methods

connect({%opts})

This will return an object that will provide persistence. It will not be an object that inherits from Tree::Persist.

%opts is described in "PARAMETERS" in Tree::Persist::DB::SelfReferential and "PARAMETERS" in Tree::Persist::File::XML.

create_datastore({%opts})

This will create a new datastore for a tree. It will then return the object used to create that datastore, as if you had called "connect({%opts})".

%opts is described in "PARAMETERS" in Tree::Persist::DB::SelfReferential, "PARAMETERS" in Tree::Persist::File::XML and "PARAMETERS" in Tree::Persist::File::XMLWithSingleQuotes.

Behaviors

These behaviors apply to the object returned from "connect({%opts})" or "create_datastore({%opts})".

autocommit()

This is a Boolean option that determines whether or not changes to the tree will committed to the datastore immediately or not. The default is true. This will return the current setting.

tree()

This returns the tree.

commit()

This will save all changes made to the tree associated with this Tree::Persist object.

This is a no-op if autocommit is true.

rollback()

This will undo all changes made to the tree since the last commit. If there were any changes, it will reload the tree from the datastore.

This is a no-op if autocommit is true.

NOTE: Any references to any of the nodes in the tree as it was before rollback() is called will not refer to the same node of $persist -> tree after rollback().

FAQ

How do I control the database used for testing?

The tests default to using $ENV{DBI_DSN}, $ENV{DBI_USER} and $ENV{DBI_PASS}, so you can set them to anything.

If $ENV{DBI_DSN} is empty, tests use DBD::SQLite for the database. In this case, a temporary directory is used for each test. This is why DBD::SQLite is listed as a pre-requisite.

CODE COVERAGE

We use Devel::Cover to test the code coverage of our tests. Below is the Devel::Cover report on this module's V 0.99 test suite.

---------------------------- ------ ------ ------ ------ ------ ------ ------
File						   stmt   bran   cond	sub	pod   time  total
---------------------------- ------ ------ ------ ------ ------ ------ ------
blib/lib/Tree/Persist.pm	  100.0   83.3	n/a  100.0  100.0   17.7   97.6
.../lib/Tree/Persist/Base.pm  100.0   88.9  100.0  100.0  100.0   20.0   98.3
blib/lib/Tree/Persist/DB.pm   100.0	n/a	n/a  100.0	n/a	3.1  100.0
...ist/DB/SelfReferential.pm  100.0   93.8	n/a  100.0	n/a   36.3   99.2
.../lib/Tree/Persist/File.pm  100.0   50.0	n/a  100.0	n/a	7.7   96.7
.../Tree/Persist/File/XML.pm  100.0  100.0  100.0  100.0	n/a   15.1  100.0
Total						 100.0   89.1  100.0  100.0  100.0  100.0   98.7
---------------------------- ------ ------ ------ ------ ------ ------ ------

SUPPORT

Bugs should be reported via the CPAN bug tracker at

https://github.com/ronsavage/Tree-Persist/issues

REPOSITORY

https://github.com/ronsavage/Tree-Persist.

AUTHORS

Rob Kinyon <rob.kinyon@iinteractive.com>

Stevan Little <stevan.little@iinteractive.com>

Thanks to Infinity Interactive for generously donating our time.

Co-maintenance since V 1.01 is by Ron Savage <rsavage@cpan.org>. Uses of 'I' in previous versions is not me, but will be hereafter.

COPYRIGHT AND LICENSE

Copyright 2004, 2005 by Infinity Interactive, Inc.

http://www.iinteractive.com

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.