NAME

Data::Transactional - data structures with RDBMS-like transactions

SYNOPSIS

    use Data::Transactional;

    my $data = Data::Transactional->new(type => 'hash');
    $data->{food_and_drink} = [ [], [] ];
    $data->checkpoint();
    $data->{food_and_drink}->[0] = [qw(pie curry chips)];
    $data->checkpoint();
    $data->{food_and_drink}->[1] = [qw(beer gin whisky)];
    $data->rollback();   # back to last checkpoint

METHODS

new

The constructor. This takes named parameters. The only parameter so far is:

type

Optional parameter, taking either 'ARRAY' or 'HASH' as its value (case- insensitive), to determine what data type to base the structure on. Regardless of what you choose for the first level of the structure, you may use whatever you like further down the tree. If not supplied, this defaults to 'HASH'.

checkpoint

Saves the current state of the structure so that we can roll back to it.

commit

Discards the most recent saved state, so it can no longer be rolled back. Why do this? Well, throwing away the history saves a load of memory. It is a fatal error to commit() when there's no saved states.

commit_all

Throws away all saved states, effectively committing all current transactions.

rollback

Revert the data structure to the last checkpoint. To roll back beyond the first checkpoint is a fatal error.

rollback_all

Roll back all changes.

current_state

Return a reference to the current state of the underlying object.

IMPLEMENTATION NOTES

This module relies on two other packages which are included in the same file - Data::Transactional::Hash and Data::Transactional::Array. These are where the magic really happens. These implement everything needed for tie()ing those structures, plus their own checkpoint(), commit() and rollback() methods. When you create a Data::Transactional object, what you really get is one of these tied structures, reblessed into the Data::Transactional class. The transactional methods simply call through to the same method on the underlying tied structure.

This is loosely inspired by DBM::Deep.

BUGS/WARNINGS

I assume that $[ is zero.

Storing blessed objects in a Data::Transactional structure is not supported. I suppose it could be, but there's no sane way that they could be transactionalised. This also applies to tie()d objects. Please note that in the case of tie()d objects, we don't do a great deal of checking, so things may break in subtle and hard-to-debug ways.

The precise details of how the transactional methods affect sub-structures in your data may change before a 1.0 release. If you have suggestions for how it could be improved, do please let me know.

The SPLICE() operation is *not defined* for transactionalised arrays, because it makes my brane hurt. If you want to implement this please do! Remember that you should use STORE() to put each new entry in the array, as that will properly handle adding complex data structures.

No doubt there are others. When submitting a bug report please please please include a test case, in the form of a .t file, which will fail with my version of the module and pass once the bug is fixed. If you include a patch as well, that's even better!

FEEDBACK

I welcome all comments - both praise and constructive criticism - about my code. If you have a question about how to use it please read *all* of the documentation first, and let me know what you have tried and how the results differ from what you wanted or expected.

I do not consider blind, automatically generated and automatically sent error reports to be constructive. Don't send them, you'll only get flamed.

AUTHOR

David Cantrell <david@cantrell.org.uk>

LICENCE

This software is Copyright 2004 David Cantrell. You may use, modify and distribute it under the same terms as perl itself.