NAME

Yote - Persistant Perl container objects in a directed graph of lazilly loaded nodes.

DESCRIPTION

This is for anyone who wants to store arbitrary structured state data and doesn't have the time or inclination to write a schema or configure some framework. This can be used orthagonally to any other storage system.

SYNOPSIS

 use Yote;

 my $store = Yote::open_store( '/path/to/data-directory' );

 my $root_node = $store->fetch_root;

 $root_node->add_to_myList( $store->newobj( { 
    someval  => 123.53,
    somehash => { A => 1 },
    someobj  => $store->newobj( { foo => "Bar" } );
 } );
 # the root node now has a list 'myList' attached to it with the single 
 # value of a yote object that yote object has two fields, 
 # one of which is an other yote object.
 
 $root_node->add_to_myList( 42 );

 $root_node->set_field( "Value" );

 my $val = $root_node->get_value( "default" );
 # $val eq 'default'

 $root_node->set_value( "Something Else" );

 my $val = $root_node->get_value( "default" );
 # $val eq 'Something Else'

 my $myList = $root_node->get_myList;

 for my $example (@$myList) {
    print ">$example\n";
 }

 my $someid = $root_node->get_someobj->{ID};

 my $someref = $store->fetch( $someid );

 $myList->[0]->set_condition( "About to be recycled" );
 delete $myList->[0];

 $store->stow_all;
 $store->run_recycler;

PUBLIC METHODS

open_store( '/path/to/directory' )

Starts up a persistance engine and returns it.

NAME

 Yote::ObjStore - manages Yote::Obj objects in a graph.

DESCRIPTION

The Yote::ObjStore does the following things :

 * fetches the root object
 * creates new objects
 * fetches existing objects by id
 * saves all new or changed objects
 * finds objects that cannot connect to the root node and recycles them

fetch_root

 Returns the root node of the graph. All things that can be 
trace a reference path back to the root node are considered active
and are not recycled when the recyler run.

newobj( { ... data .... }, optionalClass )

 Creates a container object initialized with the 
 incoming hash ref data. The class of the object must be either
 Yote::Obj or a subclass of it. Yote::Obj is the default.

 Once created, the object will be saved in the data store when 
 $store->stow_all has been called.  If the object is not attached 
 to the root or an object that can be reached by the root, it will be 
 recycled when Yote::Obj::recycle_objects is called.

fetch( $id )

 Returns the object with the given id.

run_recycler

Does a mark and sweep and recycles all objects that do not currently have an active reference or can trace a reference path back to the root object.

stow_all

 Saves all newly created or dirty objects.

NAME

 Yote::Obj - Generic container object for graph.

DESCRIPTION

A Yote::Obj is a container class that as a specific idiom for getters and setters. This idiom is set up to avoid confusion and collision with any method names.

 # sets the 'foo' field to the given value.
 $obj->set_foo( { value => $store->newobj } );

 # returns the value for bar, and if none, sets it to 'default'
 my $bar = $obj->get_bar( "default" );

 $obj->add_to_somelist( "Freddish" );
 my $list = $obj->get_somelist;
 $list->[ 0 ] == "Freddish";


 $obj->remove_from_somelist( "Freddish" );

AUTHOR Eric Wolf coyocanid@gmail.com

COPYRIGHT AND LICENSE

       Copyright (c) 2015 Eric Wolf. All rights reserved.  This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

VERSION Version 1.2 (November 2, 2015))

cpanm Yote

perl -MCPAN -e shell
install Yote