Ron Savage > Tree-Persist-1.10 > Tree::Persist

Download:
Tree-Persist-1.10.tgz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 1.10   Source  

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 ^

Email Ron Savage at the address below.

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.

syntax highlighting: