NAME

Variable::Watcher -- Keep track of changes on my variables

SYNOPSIS

    ### keep track of scalar changes
    my $scalar : Watch(s) = 1;

    ### keep track of array changes
    my @list : Watch(l) = (1);

    ### keep track of hash changes
    my %hash : Watch(h) = (1 => 2);


    ### retrieve individual mutations:
    my @stack = Variable::Watcher->stack;
    
    ### retrieve the mutation as a printable string
    my $string = Variable::Watcher->stack_as_string;

    ### flush the logs of all the mutations so far
    Variable::Watcher->flush;
    
    ### Set the default reporting filehandle (defaults to STDERR 
    ### -- see the C<GLOBAL VARIABLES> section
    $Variable::Watcher::REPORT_FH = \*MY_FH;
    
    ### Make Variable::Watcher not print to REPORT_FH when running
    ### You will have to use the stack/stack_as_string method to
    ### retrieve the logs. See the C<GLOBAL VARIABLES> section
    $Variable::Watcher::VERBOSE = 0;

DESCRIPTION

Variable::Watcher allows you to keep track of mutations on my variables. It will record every mutation you do to a variable that is being Watched. You can retrieve these mutations as a list or as a big printable string, filtered by a regex if you like.

This is a useful debugging tool when you find your my variables in a state you did not expect.

See the CAVEATS section for the limitations of this approach.

Attributes

my $var : Watch([NAME])

In order to start Watching a variable, you must tag it as being Watched at declaration time. You can optionally give it a name to be used in the logs, rather than it's memory address (this is much recommended).

You can do this for perls three basic variable types;

SCALAR

To keep track of a scalar, and it's mutations, you could for example, do somethign like this:

    my $scalar : Watch(s) = 1;
    $scalar++;
    

The resulting output would be much like this:

   [Variable::Watcher s -> STORE] Performing 'STORE' on s passing 
   '1' at z.pl line 6
   [Variable::Watcher s -> FETCH] Performing 'FETCH' on s at z.pl 
   line 7
   [Variable::Watcher s -> STORE] Performing 'STORE' on s passing 
   '2' at z.pl line 7

Showing you when you did the first STORE, when you retrieved the value (FETCH) and when you stored the increment (STORE).

ARRAY

To keep track of an array, and it's mutation, you could for example, do something like this:

    my @list : Watch(l) = (1);
    push @list, 2;
    pop @list;

The resulting output would be much like this:

   [Variable::Watcher l -> CLEAR] Performing 'CLEAR' on l at z2.pl
   line 6
   [Variable::Watcher l -> EXTEND] Performing 'EXTEND' on l 
   passing '1' at z2.pl line 6
   [Variable::Watcher l -> STORE] Performing 'STORE' on l passing 
   '0 1' at z2.pl line 6
   [Variable::Watcher l -> PUSH] Performing 'PUSH' on l passing 
   '2' at z2.pl line 7
   [Variable::Watcher l -> FETCHSIZE] Performing 'FETCHSIZE' on l 
   at z2.pl line 7
   [Variable::Watcher l -> POP] Performing 'POP' on l at z2.pl 
   line 8

Showing you that you initialized an empty array (CLEAR), and extended it's size (EXTEND) to fit your first assignment (STORE), followed by the PUSH which adds another value to your list. Then we attempt to remove the last value, showing us how perl fetches its size (FETCHSIZE) and POPs the last value off.

HASH

To keep track of a hash, and it's mutation, you could for example, do something like this:

    my %hash : Watch(h) = (1 => 2);
    $hash{3} = 4;
    delete $hash{3};

The resulting output would be much like this:

   [Variable::Watcher h -> CLEAR] Performing 'CLEAR' on h at z3.pl
   line 6
   [Variable::Watcher h -> STORE] Performing 'STORE' on h passing 
   '1 2' at z3.pl line 6
   [Variable::Watcher h -> STORE] Performing 'STORE' on h passing 
   '3 4' at z3.pl line 7
   [Variable::Watcher h -> DELETE] Performing 'DELETE' on h 
   passing '3' at z3.pl line 8

Showing you that you initialized an empty hash (CLEAR), and STOREd it's first key/value pair. Then we STORE the second key/value pair, followed by a DELETE of the key 3.

CLASS METHODS

@stack = Variable::Watcher->stack( [name => $name, action => $action] );

Retrieves a list of Log::Message::Item objects describing the mutations of the Watched variables.

The optional name argument lets you filter based on the name you have given the variables to be Watched.

The optional action argument lets you filter on the type of action you want to retrieve (STORE or FETCH, etc).

Refer to the Log::Message manpage for details on how to work with Log::Message::Item objects.

$string = Variable::Watcher->stack_as_string( [name => $name, action => $action] );

Returns the mutation log as a printable string, optionally filterd on the criteria as described in the stack method.

@stack = Variable::Watcher->flush;

Flushes the logs of all mutations that have occurred so far. Returns the stack, like the stack method would, without filtering.

GLOBAL VARIABLES

$Variable::Watcher::REPORT_FH

This is the filehandle that all mutations are printed to. It defaults to STDERR but you can change it to any (open!) filehandle you wish.

$Variable::Watcher::VERBOSE

By default, all the mutation are printed to REPORT_FH when they occur. You can silence Variable::Watcher by setting this variable to false. Note you will then have to retrieve mutation logs via the stack or stack_as_string methods.

CAVEATS

This module can only operate on the three standard perl data types; SCALAR, ARRAY, HASH, and only Watches the first level of a variable, but not nested ones; ie, a variable within a variable is not Watched.

AUTHOR

This module by Jos Boumans <kane@cpan.org>.

COPYRIGHT

This module is copyright (c) 2005 Jos Boumans <kane@cpan.org>. All rights reserved.

This library is free software; you may redistribute and/or modify it under the same terms as Perl itself.

cpanm Variable::Watcher

perl -MCPAN -e shell
install Variable::Watcher