Marc - Sebastian Lucksch > Tie-Proxy-Changes-0.2 > Tie::Proxy::Changes

Download:
tie-proxy-changes/Tie-Proxy-Changes-0.2.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  1
Open  0
View/Report Bugs
Module Version: 0.2   Source  

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

syntax highlighting: