Eric Wolf > Yote-1.45 > Yote

Download:
Yote-1.45.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 1.45   Source  

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.

Yote only loads data as it needs too. It does not load all stored containers at once. Data is stored in a data directory and is stored using the Data::RecordStore module. A Yote container is a key/value store where the values can be strings, numbers, arrays, hashes or other Yote containers.

The entry point for all Yote data stores is the root node. All objects in the store are unreachable if they cannot trace a reference path back to this node. If they cannot, running compress_store will remove them.

There are lots of potential uses for Yote, and a few come to mind :

 * configuration data
 * data modeling
 * user preference data
 * user account data
 * game data
 * shopping carts
 * product information

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" },
                'Optional-Yote-Subclass-Package' );
 } );

 # 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 );

 #
 # New Yote container objects are created with $store->newobj. Note that
 # they must find a reference path to the root to be protected from
 # being deleted from the record store upon compression.
 #
 my $newObj = $store->newobj;

 $root_node->set_field( "Value" );

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

 $val = $root_node->get_value( "Somethign Else" );
 # $val eq 'default' (old value not overridden by a new default value)


 my $otherval = $root_node->get( 'ot3rv@l', 'other default' );
 # $otherval eq 'other default'

 $root_node->set( 'ot3rv@l', 'newy valuye' );
 $otherval2 = $root_node->get( 'ot3rv@l', 'yet other default' );
 # $otherval2 eq 'newy valuye'

 $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";
 }

 #
 # Each object gets a unique ID which can be used to fetch that
 # object directly from the store.
 #
 my $someid = $root_node->get_someobj->{ID};

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

 #
 # Even hashes and array have unique yote IDS. These can be
 # determined by calling the _get_id method of the store.
 #
 my $hash = $root_node->set_ahash( { zoo => "Zar" } );
 my $hash_id = $store->_get_id( $hash );
 my $other_ref_to_hash = $store->fetch( $hash_id );

 #
 # Anything that cannot trace a reference path to the root
 # is eligable for being removed upon compression. 
 #

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 removes 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 removed when the object store is compressed.

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
 remove when Yote::ObjStore::Compress is called.

fetch( $id )

 Returns the object with the given id.

run_recycler

compress_store

This creates a new data store with all objects removed that cannot be traced back to the root.

This will fail if the following directories exist : ${ROOT-DIRECOTRY-FOR-OBJECT-STORE}_COMPRESS_BAK ${ROOT-DIRECOTRY-FOR-OBJECT-STORE}_NEW_RECYC

The first directory is where the original object store gets backed up after the compression. If the compression is a success, it should be removed.

The second is a temporary working directory for the new copied over database.

This requires enough room on the file system to potentially double the size of the database temporarily as it is copied to a new one.

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" );

absorb( hashref )

    pulls the hash data into this object.

set( $field, $value )

    Assigns the given value to the field in this object and returns the
    assigned value.

get( $field, $default-value )

    Returns the value assigned to the field, assinging the default
    value to it if the value is currently not defined.

_init

    This is called the first time an object is created. It is not
    called when the object is loaded from storage. This can be used
    to set up defaults. This is meant to be overridden.

_init

    This is called each time the object is loaded from the data store.
    This is meant to be overridden.

AUTHOR Eric Wolf coyocanid@gmail.com ^

COPYRIGHT AND LICENSE ^

       Copyright (c) 2016 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.44 (Nov 23, 2016)) ^

syntax highlighting: