NAME
Tie::Trace - easy print debugging with tie, for watching variable
VERSION
Version 0.17
SYNOPSIS
use Tie::Trace qw/watch/; # or qw/:all/
my %hash = (key => 'value');
watch %hash;
$hash{hoge} = 'hogehoge'; # warn "main:: %hash => {hoge} => hogehgoe at ..."
my @array;
tie @array;
push @array, "array"; # warn "main:: @array [0] => array at ..."
my $scalar;
watch $scalar;
$scalar = "scalar"; # warn "main:: $scalar => scalar at ..."
DESCRIPTION
This is useful for print debugging. Using tie mechanism, you can see stored/deleted value for the specified variable.
If the stored value is scalar/array/hash ref, this can check recursively.
for example;
watch %hash;
$hash{foo} = {a => 1, b => 2}; # warn "main:: %hash => {foo} => {a => 1, b => 2}"
$hash{foo}->{a} = 2 # warn "main:: %hash => {foo}{a} => 2"
But This ignores blessed reference and tied value.
FUNCTION
This provides one function watch
from version 0.06.
Then you should use only this function. Don't use tie
function instead.
watch
watch $variables; watch $scalar, %options; watch @array, %options; watch %hash, %options;
When you
watch
variables and value is stored/delete in the variables, warn the message like as the following.main:: %hash => {key} => value at ...
If the variables has values before
watch
, it is no problem. Tie::Trace work well.my %hash = (key => 'value'); watch %hash;
OPTIONS
You can use watch
with some options.
If you want global options, see "GLOBAL VARIABLES".
key => [values/regexs/coderef]
watch %hash, key => [qw/foo bar/];
It is for hash. You can specify key name/regex/coderef for checking. Not specified/matched keys are ignored for warning. When you give coderef, this coderef receive tied value and key as arguments, it returns false, the key is ignored.
for example;
watch %hash, key => [qw/foo bar/, qr/x/]; $hash{foo} = 1 # warn ... $hash{bar} = 1 # warn ... $hash{var} = 1 # *no* warnings $hash{_x_} = 1 # warn ...
value => [contents/regexs/coderef]
watch %hash, value => [qw/foo bar/];
You can specify value's content/regex/coderef for checking. Not specified/matched are ignored for warning. When you give coderef, this coderef receive tied value and value as arguments, it returns false, the value is ignored.
for example;
watch %hash, value => [qw/foo bar/, qr/\)/]; $hash{a} = 'foo' # warn ... $hash{b} = 'foo1' # *no* warnings $hash{c} = 'bar' # warn ... $hash{d} = ':-)' # warn ...
use => [qw/hash array scalar/]
tie %hash, "Tie::Trace", use => [qw/array/];
It specify type(scalar, array or hash) of variable for checking. As default, all type will be checked.
for example;
watch %hash, use => [qw/array/]; $hash{foo} = 1 # *no* warnings $hash{bar} = 1 # *no* warnings $hash{var} = [] # *no* warnings push @{$hash{var}} = 1 # warn ...
debug => 'dumper'/coderef
watch %hash, debug => 'dumper' watch %hash, debug => sub{my($self, @v) = @_; return @v }
It specify value representation. As default, "dumper" is set. "dumper" makes value show with Data::Dumper::Dumper format(but ::Terse = 0 and ::Indent = 0). You can use coderef instead of "dumper". When you specify your coderef, its first argument is tied value and second argument is value, it should modify it and return it.
debug_value => [contents/regexs/coderef]
watch %hash, debug => sub{my($s,$v) = @_; $v =~tr/op/po/;}, debug_value => [qw/foo boo/];
You can specify debugged value's content/regex for checking. Not specified/matched are ignored for warning. When you give coderef, this coderef receive tied value and value as arguments, it returns false, the value is ignored.
for example;
watch %hash, debug => sub{my($s,$v) = @_; $v =~tr/op/po/;}, debug_value => [qw/foo boo/]; $hash{a} = 'fpp' # warn ... because debugged value is foo $hash{b} = 'foo' # *no* warnings because debugged value is fpp $hash{c} = 'bpp' # warn ... because debugged value is boo
r => 0/1
tie %hash, "Tie::Trace", r => 0;
If r is 0, this won't check recursively. 1 is default.
caller => number/[numbers]
watch %hash, caller => 2;
It effects warning message. default is 0. If you set grater than 0, it goes upstream to check.
You can specify array ref.
watch %hash, caller => [1, 2, 3];
It display following messages.
main %hash => {key} => 'hoge' at filename line 61. at filename line 383. at filename line 268.
METHODS
It is used in coderef which is passed for options, for example, key, value and/or debug_value or as the method of the returned of tied function.
storage
watch %hash, debug => sub { my($self, $v) = @_; my $storage = $self->storage; return $storage; };
This returns reference in which value(s) stored.
parent
watch %hash, debug => sub { my($self, $v) = @_; my $parent = $self->parent->storage; return $parent; };
This method returns $self's parent tied value.
for example;
watch my %hash; my %hash2; $hash{1} = \%hash2; my $tied_hash2 = tied %hash2; print tied %hash eq $tied_hash2->parent; # 1
GLOBAL VARIABLES
%Tie::Trace::OPTIONS
This is Global options for Tie::Trace. If you don't specify any options, this option is used. If you use override options, you use
watch
with options.%Tie::Trace::OPTIONS = (debug => undef, ...); # global options will be used watch my %hash; # your options will be used watch my %hash2, debug => 'dumper', ...;
$Tie::Trace::QUIET
If this value is true, Tie::Trace warn nothing.
watch my %hash; $hash{1} = 1; # warn something $Tie::Trace::QUIET = 1; $hash{1} = 2; # no warn
AUTHOR
Ktat, <ktat.is at gmail.com>
BUGS
Please report any bugs or feature requests to
bug-tie-debug at rt.cpan.org
, or through the web interface at
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Tie-Trace.
I will be notified, and then you'll automatically be notified of progress on
your bug as I make changes.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc Tie::Trace
You can also find documentation written in Japanese(euc-jp) for this module with the perldoc command.
perldoc Tie::Trace_JP
You can also look for information at:
AnnoCPAN: Annotated CPAN documentation
CPAN Ratings
RT: CPAN's request tracker
Search CPAN
ACKNOWLEDGEMENT
JN told me the idea of new warning message(from 0.06).
COPYRIGHT & LICENSE
Copyright 2006-2010 Ktat, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.