Carp::Datum 0.1.3

Carp::Datum is a Perl module used for debugging and tracing.

SYNOPSIS

# In modules
use Carp::Datum;

# Programming by contract
sub routine {
DFEATURE my $f_, "optional message"; # $f_ is a lexical lvalue here
my ($a, $b) = @_;
DREQUIRE $a > $b, "a > b";
$a += 1; $b += 1;
DASSERT $a > $b, "ordering a > b preserved";
my $result = $b - $a;
DENSURE $result < 0;
return DVAL $result;
}

# Tracing
DTRACE "this is a debug message";
DTRACE TRC_NOTICE, "note: a = ", $a, " is positive";
DTRACE {-level => TRC_NOTICE, -marker => "!!"}, "note with marker";

# Returning
return DVAL $scalar; # single value
return DARY @list; # list of values

# In applications main
use Carp::Datum qw(:all on); # turns Datum "on" or "off"

DLOAD_CONFIG(-file => "debug.cf", -config => "config string");

The Carp::Datum module brings powerful debugging and tracing features to development code: automatic flow tracing, returned value tracing, assertions, and debugging traces. Its various functions may be customized dynamically (i.e. at run time) via a configuration language allowing selective activation on a routine, file, or object type basis. See Carp::Datum::Cfg for configuration defails.
Carp::Datum traces are implemented on top of Log::Agent and go to its debugging channel. This lets the application have full control of the final destination of the debugging information (logfile, syslog, etc...).

Carp::Datum can be globally turned on or off by the application. It is off by default, which means no control flow tracing (routine entry and exit), and no returned value tracing. However, assertions are still fully monitored, and the DTRACE calls are redirected to Log::Agent.

The C version of Carp::Datum is implemented with macros, which may be redefined to nothing to remove all assertions in the released code. The Perl version cannot be handled that way, but comes with a Carp::Datum::Strip module that will lexically remove all the assertions, leaving only DTRACE calls. Modules using Carp::Datum can make use of Carp::Datum::MakeMaker in their Makefile.PL to request stripping at build time. See Carp::Datum::MakeMaker for instructions.

Here is a small example showing what traces look like, and what happens by default on assertion failure. Since Log::Agent is not being customized, the debugging channel is STDERR. In real life, one would probably customize Log::Agent with a file driver, and redirect the debug channel to a file separate from both STDOUT and STDERR.