Variable::Watcher -- Keep track of changes on my variables
my
### 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;
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.
Variable::Watcher
Watch
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.
CAVEATS
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;
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).
STORE
FETCH
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;
[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.
CLEAR
EXTEND
PUSH
FETCHSIZE
POP
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};
[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.
DELETE
3
Retrieves a list of Log::Message::Item objects describing the mutations of the Watched variables.
Log::Message::Item
The optional name argument lets you filter based on the name you have given the variables to be Watched.
name
The optional action argument lets you filter on the type of action you want to retrieve (STORE or FETCH, etc).
action
Refer to the Log::Message manpage for details on how to work with Log::Message::Item objects.
Log::Message
Returns the mutation log as a printable string, optionally filterd on the criteria as described in the stack method.
stack
Flushes the logs of all mutations that have occurred so far. Returns the stack, like the stack method would, without filtering.
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.
STDERR
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.
REPORT_FH
false
stack_as_string
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.
SCALAR
ARRAY
HASH
This module by Jos Boumans <kane@cpan.org>.
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.
1 POD Error
The following errors were encountered while parsing the POD:
You forgot a '=back' before '=head1'
To install Variable::Watcher, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Variable::Watcher
CPAN shell
perl -MCPAN -e shell install Variable::Watcher
For more information on module installation, please visit the detailed CPAN module installation guide.