NAME

Devel::Carnivore - Spy on your hashes (and objects)

SYNOPSIS

  use Devel::Carnivore;
  
  sub new_attribute {
    my %self : Watch("myName") = ();            

    bless \%self, shift;
  }

  sub new_functional {
    my $self  = {};             
    watch $self, "myName";
    bless $self
  }

  sub new_blessed {
    my $self  = {};     
    bless $self;
    watch $self, "myName";
    return $self;
  }

  sub new_scalar_attribute {
    my $self : Watch("myName") = {};            
    bless $self
  }

DESCRIPTION

This module allows you to debug your hashes and, in particular, your objects based on hashes without using the perl debugger. There are several good reasons to do this. Among them:

1) You're too stupid to use the perl debugger (This is true for me)

2) You're building web applications and the perl debugger doesn't work very well in that environment

Obviously, this module does not provide you with a complete debugger. All it does is helping you keep track of the state changes which occur to your objects.

Output

By default all output is written to STDERR. You may change this behavior by assigning a valid output filehandle to $Devel::Carnivore::OUT.

Everytime the hash which is being watched by this module is assigned to, a message like this is created: > ProgLang: "cool" changed from "Java" to "Perl" at devel.pl line 30

So what does this tell you?

You have a Perl file named devel.pl. On line 30 your code changed the value of the key "cool" from "Java" to "Perl". In order, to identify this hash you optionally named it "ProgLang".

USAGE

There are several ways to declare a hash as being watched. "aName" is always optional. You can use it to identify a certain hash in the output.

The following text will assume "place under observation" means "tie to Devel::Carnivore"

functional

  The function C<watch> (which is exported by default) will place it's first
  para under observation.

  C<watch $hashref, "aName">
  C<watch \%hash, "aName">

scalar attribute

  The attribute Watch may be placed on any scalar which is immediately
  assigned an hash reference. It will put this hash reference under observation.

  C<my $scalar : Watch("aName") = {};>
  

hash attribute

  The attribute Watch may be placed on any hash to put it under observation.

  C<my %hash : Watch("aName") = ();>

stop tracing

  This function (which is exported by default) will END the observation of it's
  first para.

  C<unwatch $hashref>
  C<unwatch \%hash>   

WARNING

Please do NOT use this module on any hashes which are tied to any other class during their livetime. That won't work.

BUGS

It seems to work alright, but this module is in very early state.

It would be nice to have a complete stack trace for each state change and some tool to format that output nicely.

The module could easily extended to work on arrays. Currently I don't feel the need.

AUTHOR

Malte Ubl, <malteubl@gmx.de>

COPYRIGHT

Copyright 2002 by Malte Ubl <malteubl@gmx.de>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html

cpanm Devel::Carnivore

perl -MCPAN -e shell
install Devel::Carnivore