NAME

Tie::Proxy::Changes - Track changes in your tied objects

SYNOPSIS

In any tied class:

    use Tie::Proxy::Changes;
    use Tie::Hash;
    
    our @ISA=qw/Tie::StdHash/;
   
    sub FETCH {
        my $self=shift;
        my $key=shift;
        if (exists $self->{$key}) {
            return Tie::Proxy::Changes->new($self,$key,$self->{$key});
        }
        else {
            return Tie::Proxy::Changes->new($self,$key);
        }
    }

DESCRIPTION

Sometimes a tied object needs to keep track of all changes happening to its data. This includes substructures with multi-level data. Returning a Tie::Proxy::Changes object instead of the raw data will result in a STORE call whenever the data is changed.

Here is a small example to illustrate to problem.

    package main;
    tie %data 'TiedObject';
    $data{FOO}={}; #Calls STORE(FOO,{})
    $data{FOO}->{Bar}=1; #calls just FETCH.

But when TiedObject is changed, it does this:

    package TiedObject;
    #...
    sub FETCH {
        my $self=shift;
        my $key=shift;
        #... $data=something.
        # return $data # Not anymore.
        return Tie::Proxy::Changes->new($self,$key,$data);
    }
    package main;
    tie %data 'TiedObject';
    $data{FOO}={}; #Calls STORE(FOO,{})
    $data{FOO}->{Bar}=1; #calls FETCH and then STORE(FOO,{Bar=>1}).

AUTOVIVIFICATION

This module can also (or exclusivly) be used to make autovivification work. Some tied datastructures convert all mulit-level data they get into tied objects.

When perl gets an undef from a FETCH call, it calls STORE with an empty reference to an array or a hash and then changes that hash. Some tied objects however can not keep this reference, because they save it in a different way.

The solution is to have FETCH return an empty Tie::Proxy::Changes object, and if the object is changed, STORE of the tied object will be called with the given key

    my $self=shift;
    my $key=shift;
    ...
    #return undef; # Not anymore
    return Tie::Proxy::Changes->new($self,$key);

If the object is just tested for existance of substructures, no STORE is called.

METHODS

new (OBJECT, KEY, [DATA])

Creates a new Tie::Proxy::Changes, on every change of its content OBJECT->STORE(KEY,MODIFIED DATA) is called.

For TIESCALAR objects, KEY has to be set to undef.

INTERNAL METHODS

SCALAR

Returns the size of the data.

See perltie (Somehow Pod::Coverage annoys me about this method).

BUGS

If you find any bugs, please drop me a mail.

SEE ALSO

perltie

LICENSE

Tie::Proxy::Changes is published under the terms of the MIT license, which basically means "Do with it whatever you want". For more information, see the LICENSE file that should be enclosed with this distribution. A copy of the license is (at the time of this writing) also available at http://www.opensource.org/licenses/mit-license.php.

AUTHOR

Marc "Maluku" Sebastian Lucksch

perl@marc-s.de

cpanm Tie::Proxy::Changes

perl -MCPAN -e shell
install Tie::Proxy::Changes