The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Tie-Trace-0.16
River stage one • 1 direct dependent • 1 total dependent
9 ++
/ Tie::Trace

NAME

Tie::Trace - easy print debugging with tie, for watching variable

VERSION

Version 0.16

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:

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.