# NAME Tie::Trace - easy print debugging with tie, for watching variable # VERSION Version 0.15 # 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"](#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](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 [http://annocpan.org/dist/Tie-Trace](http://annocpan.org/dist/Tie-Trace) - CPAN Ratings [http://cpanratings.perl.org/d/Tie-Trace](http://cpanratings.perl.org/d/Tie-Trace) - RT: CPAN's request tracker [http://rt.cpan.org/NoAuth/Bugs.html?Dist=Tie-Trace](http://rt.cpan.org/NoAuth/Bugs.html?Dist=Tie-Trace) - Search CPAN [http://search.cpan.org/dist/Tie-Trace](http://search.cpan.org/dist/Tie-Trace) # 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.