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.