Tree::Persist - A transparent persistence layer for Tree and its children
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');
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.
The plugins that have been written are:
Tree::Persist::DB::SelfReferential
Tree::Persist::File::XML
This module uses double-quotes around the values of tag attributes.
Tree::Persist::File::XMLWithSingleQuote
This module uses single-quotes around the values of tag attributes.
It is included simply to demonstrate using a user-supplied class for deflation/inflation.
See t/save_and_load.t for sample code.
Please refer to their documentation for the appropriate options for connect() and create_datastore().
connect()
create_datastore()
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.
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.
These behaviors apply to the object returned from "connect({%opts})" or "create_datastore({%opts})".
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.
This returns the tree.
This will save all changes made to the tree associated with this Tree::Persist object.
This is a no-op if autocommit is true.
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.
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().
rollback()
$persist -> tree
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.
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 ---------------------------- ------ ------ ------ ------ ------ ------ ------
Email Ron Savage at the address below.
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 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.
To install Tree::Persist, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Tree::Persist
CPAN shell
perl -MCPAN -e shell install Tree::Persist
For more information on module installation, please visit the detailed CPAN module installation guide.