| 1 |
# -*- Mode: perl -*- |
| 2 |
# |
| 3 |
# $Id: Datum.pm,v 0.1.1.2 2001/07/13 17:04:58 ram Exp $ |
| 4 |
# |
| 5 |
# Copyright (c) 2000-2001, Christophe Dehaudt & Raphael Manfredi |
| 6 |
# |
| 7 |
# You may redistribute only under the terms of the Artistic License, |
| 8 |
# as specified in the README file that comes with the distribution. |
| 9 |
# |
| 10 |
# HISTORY |
| 11 |
# $Log: Datum.pm,v $ |
| 12 |
# Revision 0.1.1.2 2001/07/13 17:04:58 ram |
| 13 |
# patch2: integrated mods made by CDE: |
| 14 |
# patch2: added DEBUG CONFIGURATION section |
| 15 |
# patch2: added HISTORY AND CREDITS section |
| 16 |
# patch2: fixed demo script to include leading DFEATURE call |
| 17 |
# |
| 18 |
# Revision 0.1.1.1 2001/05/30 21:09:36 ram |
| 19 |
# patch1: added LIMITATIONS section to warn about stringify overloading |
| 20 |
# |
| 21 |
# Revision 0.1 2001/03/31 10:04:36 ram |
| 22 |
# Baseline for first Alpha release. |
| 23 |
# |
| 24 |
# $EndLog$ |
| 25 |
# |
| 26 |
|
| 27 |
use strict; |
| 28 |
|
| 29 |
package Carp::Datum; |
| 30 |
|
| 31 |
use vars qw($VERSION); |
| 32 |
$VERSION = '0.101'; |
| 33 |
|
| 34 |
use Log::Agent; |
| 35 |
use Log::Agent qw(logwrite); |
| 36 |
|
| 37 |
use Getargs::Long qw(ignorecase); |
| 38 |
|
| 39 |
use Carp::Datum::Flags; |
| 40 |
require Carp::Datum::Parser; |
| 41 |
|
| 42 |
require Exporter; |
| 43 |
use vars qw(@ISA @EXPORT @EXPORT_OK @EXPORT_FAIL %EXPORT_TAGS); |
| 44 |
@ISA = qw(Exporter); |
| 45 |
@EXPORT = (qw(DLOAD_CONFIG |
| 46 |
DFEATURE |
| 47 |
DTRACE |
| 48 |
DASSERT |
| 49 |
VERIFY |
| 50 |
DREQUIRE |
| 51 |
DENSURE |
| 52 |
DVAL |
| 53 |
DARY |
| 54 |
DVOID |
| 55 |
implies |
| 56 |
equiv |
| 57 |
), |
| 58 |
@Carp::Datum::Flags::EXPORT); |
| 59 |
@EXPORT_FAIL = qw(on off); |
| 60 |
@EXPORT_OK = qw(on off); |
| 61 |
%EXPORT_TAGS = (all => \@EXPORT); |
| 62 |
|
| 63 |
use vars qw( |
| 64 |
$DBG |
| 65 |
$DEBUG_TABLE |
| 66 |
$CFG |
| 67 |
); |
| 68 |
|
| 69 |
$DBG = DBG_OFF; |
| 70 |
|
| 71 |
require Carp::Datum::Cfg; |
| 72 |
$CFG = Carp::Datum::Cfg->make(); |
| 73 |
|
| 74 |
|
| 75 |
$DEBUG_TABLE = {default => { debug => [DBG_ALL, 0], |
| 76 |
trace => [TRC_ALL, 0], |
| 77 |
args => -1 |
| 78 |
}, |
| 79 |
alias => [] |
| 80 |
}; |
| 81 |
|
| 82 |
|
| 83 |
# |
| 84 |
# ->export_fail |
| 85 |
# |
| 86 |
# Called by Exporter when one of the symbols listed in @EXPORT_FAIL is |
| 87 |
# indeed exported. |
| 88 |
# |
| 89 |
sub export_fail { |
| 90 |
my ($self, @syms) = @_; |
| 91 |
my @failed; |
| 92 |
foreach my $sym (@syms) { |
| 93 |
if ($sym eq 'on') { $DBG = DBG_ON } |
| 94 |
elsif ($sym eq 'off') { $DBG = DBG_OFF } |
| 95 |
else { push(@failed, $sym) } |
| 96 |
} |
| 97 |
|
| 98 |
Log::Agent::DATUM_is_here() if $DBG; # Intercept Log::Agent traces |
| 99 |
|
| 100 |
return @failed; # Empty list if OK |
| 101 |
} |
| 102 |
|
| 103 |
# |
| 104 |
# DLOAD_CONFIG |
| 105 |
# |
| 106 |
# read the debug input to get the debug instructions. Filename |
| 107 |
# content and raw string configuration are concatened to be parsed. |
| 108 |
# |
| 109 |
# Arguments: |
| 110 |
# -file => $filename: file to load [optionnal] |
| 111 |
# -config => $string: string which contains config set up [optionnal] |
| 112 |
# -trace => boolean: print the parsing result when true [optionnal] |
| 113 |
# |
| 114 |
sub DLOAD_CONFIG { |
| 115 |
return unless $DBG; |
| 116 |
|
| 117 |
my ($dump_parser, @remaining) = cgetargs(@_, {-strict => 0, -extra => 1}, |
| 118 |
[qw(trace)]); |
| 119 |
|
| 120 |
require Carp::Datum::Cfg; |
| 121 |
$CFG = Carp::Datum::Cfg->make(@remaining); |
| 122 |
|
| 123 |
Log::Agent::DATUM_is_here(); # Intercept Log::Agent traces |
| 124 |
|
| 125 |
return unless $dump_parser == 1; |
| 126 |
|
| 127 |
require Data::Dumper; |
| 128 |
DTRACE(TRC_DEBUG, Data::Dumper::Dumper($CFG->cfg_table)); |
| 129 |
|
| 130 |
return; |
| 131 |
} |
| 132 |
|
| 133 |
|
| 134 |
# |
| 135 |
# DFEATURE |
| 136 |
# |
| 137 |
# |
| 138 |
sub DFEATURE { |
| 139 |
return unless $DBG && $CFG->check_debug(DBG_FLOW); |
| 140 |
|
| 141 |
# |
| 142 |
# This routine is usually called as: |
| 143 |
# |
| 144 |
# DFEATURE(my $f, "any", "other", $param); |
| 145 |
# |
| 146 |
# so the first argument is a lexical lvalue. |
| 147 |
# |
| 148 |
# To ensure the tracing capabilities, we rely on the immediate collecting |
| 149 |
# of the "$f" lexical as soon as the scope of the routine is left: the |
| 150 |
# DESTROY hook will be called on the Carp::Datum object, so we'll know. |
| 151 |
# |
| 152 |
# One day, Perl's garbage collecting scheme may loose this systematic |
| 153 |
# destroying of lexicals by differing object reclaiming if reference |
| 154 |
# counting is abandonned and GC algorithms requiring object traversal |
| 155 |
# are implemented. |
| 156 |
# |
| 157 |
# When that day comes, the alternative will be to systematically use |
| 158 |
# the DVOID, DVAL and DARY on returning, and to maintain a parallel |
| 159 |
# stack here. Exceptions will be detected by tagging the depth level |
| 160 |
# and checking it at DVOID, DVAL or DARY time. This will probably require |
| 161 |
# probing the subroutine name of our caller, and computing the depth |
| 162 |
# of the perl stack if the caller does not match. And to handle recursion, |
| 163 |
# and exceptions happening in there, to flag places where eval() is used |
| 164 |
# so that we know where to look if the stack depth is not as deep as |
| 165 |
# expected. |
| 166 |
# |
| 167 |
# A huge work anyway, so despite reference counting not being the best |
| 168 |
# GC algorithm, it has the nice property of being somewhat predictible. |
| 169 |
# It's usually bad to depend on such knowledge, but here that's very, |
| 170 |
# and I mean VERY, convenient. |
| 171 |
# |
| 172 |
# -- RAM, 01/10/2000 |
| 173 |
# |
| 174 |
|
| 175 |
$_[0] = new Carp::Datum(@_[1 .. $#_]); |
| 176 |
return; |
| 177 |
|
| 178 |
# XXX use weakrefs in 5.6 and above to keep track of those objects in |
| 179 |
# XXX a parallel stack, and to fix display ordering in DESTROY, where |
| 180 |
# XXX the caller is sometimes destroyed before the callee. |
| 181 |
} |
| 182 |
|
| 183 |
# |
| 184 |
# DVOID |
| 185 |
# DVAL |
| 186 |
# DARY |
| 187 |
# |
| 188 |
# Print the return code and effectively return it. |
| 189 |
# |
| 190 |
# When the given parameter is an array and the return context is also |
| 191 |
# an array, there is no trouble to determine what is returned: it is the |
| 192 |
# array. |
| 193 |
# |
| 194 |
# But when the context is a scalar, it is more difficult since the |
| 195 |
# parameter might be either a regular array, or a list of |
| 196 |
# statement. For the fist case, the function must return the number of |
| 197 |
# elements , and the latter form must return the last statements |
| 198 |
# value. |
| 199 |
# |
| 200 |
# Use DVOID when you would otherwise say "return;". |
| 201 |
# Use DVAL to return a scalar, or the last element of a list when called in |
| 202 |
# scalar context, the list when called in array context (wantarray). |
| 203 |
# Use DARY when you return a list, and it will be taken as the amount of items |
| 204 |
# when you're called in scalar context, and as the list otherwise. |
| 205 |
# |
| 206 |
# To be properly stripped when assertions are to be removed from the code, |
| 207 |
# one should say: |
| 208 |
# |
| 209 |
# return DVAL 1; # will become "return 1;" |
| 210 |
# |
| 211 |
# and NOT: |
| 212 |
# |
| 213 |
# return DVAL(1); # will really become "return (1);" |
| 214 |
# |
| 215 |
# unless you really mean: |
| 216 |
# |
| 217 |
# return DVAL (1); |
| 218 |
# |
| 219 |
# i.e. the DVOID, DVAL and DARY words are to be thought as "tags" that will be |
| 220 |
# removed, without otherwise touching anything else. |
| 221 |
# |
| 222 |
|
| 223 |
sub DVOID { |
| 224 |
return unless $DBG && $CFG->check_debug(DBG_RETURN); |
| 225 |
|
| 226 |
trace("Returning" . where(1)); |
| 227 |
return; |
| 228 |
} |
| 229 |
|
| 230 |
sub DVAL { |
| 231 |
return wantarray ? @_: $_[$#_] |
| 232 |
unless $DBG && $CFG->check_debug(DBG_RETURN); |
| 233 |
|
| 234 |
# fix the arg list when the value to return is undef |
| 235 |
@_ = (undef) if $#_ == -1; |
| 236 |
|
| 237 |
trace("Returning: " . |
| 238 |
(wantarray ? |
| 239 |
"(" . (join ', ', (map {data_format($_)} @_)) . ")": |
| 240 |
data_format($_[$#_])) .where(1)); |
| 241 |
return (wantarray ? @_ : $_[$#_]); |
| 242 |
} |
| 243 |
|
| 244 |
sub DARY { |
| 245 |
return @_ unless $DBG && $CFG->check_debug(DBG_RETURN); |
| 246 |
|
| 247 |
# fix the arg list when the value to return is undef |
| 248 |
# @_ = () if $#_ == -1; |
| 249 |
|
| 250 |
# get the scalar of the array |
| 251 |
my $a = @_; |
| 252 |
|
| 253 |
trace("Returning: " . |
| 254 |
(wantarray ? |
| 255 |
"(" . (join ', ', (map {data_format($_)} @_)) . ")": |
| 256 |
data_format(scalar @_)) .where(1)); |
| 257 |
|
| 258 |
return @_; |
| 259 |
} |
| 260 |
|
| 261 |
# |
| 262 |
# DTRACE |
| 263 |
# |
| 264 |
# Arguments Form 1: |
| 265 |
# {-level => level, -marker => marker}, message |
| 266 |
# |
| 267 |
# Arguments Form 2: |
| 268 |
# level, message |
| 269 |
# |
| 270 |
# Arguments Form 3: |
| 271 |
# message |
| 272 |
# |
| 273 |
sub DTRACE { |
| 274 |
return if $DBG && !$CFG->check_debug(DBG_TRACE); |
| 275 |
|
| 276 |
# parse arguments |
| 277 |
my $level = TRC_DEBUG; |
| 278 |
my $marker = ''; |
| 279 |
if (ref $_[0] eq 'HASH') { |
| 280 |
my $hashref = shift; |
| 281 |
if (defined $hashref->{-level}) { |
| 282 |
$level = $hashref->{-level}; |
| 283 |
} |
| 284 |
if (defined $hashref->{-marker}) { |
| 285 |
$marker = $hashref->{-marker}; |
| 286 |
} |
| 287 |
} |
| 288 |
else { |
| 289 |
if ($_[0] =~ /^\d+$/) { |
| 290 |
# take the first argument as level if it is not alone |
| 291 |
if ($#_ > 0) { |
| 292 |
$level = shift; |
| 293 |
} |
| 294 |
} |
| 295 |
} |
| 296 |
|
| 297 |
if ($DBG) { |
| 298 |
# check whether tracing level is permitted |
| 299 |
return unless $CFG->check_trace($level); |
| 300 |
|
| 301 |
trace(join('', @_) . where(1), $marker); |
| 302 |
return; |
| 303 |
} |
| 304 |
|
| 305 |
# |
| 306 |
# No debugging activated, call must be remapped to Log::Agent. |
| 307 |
# |
| 308 |
|
| 309 |
%Carp::Datum::logmap = ( |
| 310 |
TRC_EMERGENCY() => [\&logdie, undef], # panic |
| 311 |
TRC_ALERT() => [\&logerr, undef], |
| 312 |
TRC_CRITICAL() => [\&logerr, undef], |
| 313 |
TRC_ERROR() => [\&logerr, undef], |
| 314 |
TRC_WARNING() => [\&logwarn, undef], |
| 315 |
TRC_NOTICE() => [\&logsay, undef], |
| 316 |
TRC_INFO() => [\&logtrc, 'info'], |
| 317 |
TRC_DEBUG() => [\&logtrc, 'debug'], |
| 318 |
) unless defined %Carp::Datum::logmap; |
| 319 |
|
| 320 |
my $entry = $Carp::Datum::logmap{$level}; |
| 321 |
|
| 322 |
# |
| 323 |
# Use magic "goto &" to forget about the DTRACE call. |
| 324 |
# |
| 325 |
# That's important if they use the caller indication feature |
| 326 |
# in Log::Agent. Otherwise, all calls would be traced from here. |
| 327 |
# |
| 328 |
|
| 329 |
if (defined $entry) { |
| 330 |
my ($fn, $loglvl) = @$entry; |
| 331 |
@_ = defined $loglvl ? ($loglvl, join('', @_)) : (join '', @_); |
| 332 |
goto &$fn; |
| 333 |
} else { |
| 334 |
@_ = (join '', @_); |
| 335 |
goto &logerr; |
| 336 |
} |
| 337 |
|
| 338 |
return; |
| 339 |
} |
| 340 |
|
| 341 |
# |
| 342 |
# DASSERT |
| 343 |
# |
| 344 |
sub DASSERT { |
| 345 |
return assert(DBG_PANIC|DBG_STACK, 'assertion', @_) unless $DBG; |
| 346 |
|
| 347 |
my $dbg_flag = $CFG->flag('debug'); |
| 348 |
return unless $dbg_flag & DBG_ASSERT; |
| 349 |
|
| 350 |
assert($dbg_flag, 'assertion', @_); |
| 351 |
} |
| 352 |
|
| 353 |
# |
| 354 |
# DREQUIRE |
| 355 |
# |
| 356 |
sub DREQUIRE { |
| 357 |
return assert(DBG_PANIC|DBG_STACK, 'pre-condition', @_) unless $DBG; |
| 358 |
|
| 359 |
my $dbg_flag = $CFG->flag('debug'); |
| 360 |
return unless $dbg_flag & DBG_REQUIRE; |
| 361 |
|
| 362 |
assert($dbg_flag, 'pre-condition', @_); |
| 363 |
} |
| 364 |
|
| 365 |
# |
| 366 |
# VERIFY |
| 367 |
# |
| 368 |
# same behavior as a DREQUIRE, but it cannot be disabled with the |
| 369 |
# Datum debug flag. It is useful to protect the edge of a module from |
| 370 |
# the external invocation. |
| 371 |
sub VERIFY { |
| 372 |
my ($test, $string) = @_; |
| 373 |
|
| 374 |
assert(DBG_PANIC|DBG_STACK, 'verify', @_); |
| 375 |
} |
| 376 |
|
| 377 |
|
| 378 |
# |
| 379 |
# DENSURE |
| 380 |
# |
| 381 |
sub DENSURE { |
| 382 |
return assert(DBG_PANIC|DBG_STACK, 'post-condition', @_) unless $DBG; |
| 383 |
|
| 384 |
my $dbg_flag = $CFG->flag('debug'); |
| 385 |
return unless $dbg_flag & DBG_ENSURE; |
| 386 |
|
| 387 |
assert($dbg_flag, 'post-condition', @_); |
| 388 |
} |
| 389 |
|
| 390 |
|
| 391 |
# |
| 392 |
# implies |
| 393 |
# |
| 394 |
# Implement the logical operation (migth be useful for assertion) |
| 395 |
# |
| 396 |
sub implies { |
| 397 |
return (!$_[0]) || $_[1]; |
| 398 |
} |
| 399 |
|
| 400 |
# |
| 401 |
# equiv |
| 402 |
# |
| 403 |
# Implement the logical operation (migth be useful for assertion) |
| 404 |
# |
| 405 |
sub equiv { |
| 406 |
return !$_[0] == !$_[1]; |
| 407 |
} |
| 408 |
|
| 409 |
# |
| 410 |
# assert |
| 411 |
# |
| 412 |
# perhaps modify the signature when caching features is implemented for |
| 413 |
# CFG |
| 414 |
# |
| 415 |
sub assert { |
| 416 |
my $debug_flag = shift; |
| 417 |
my $assert_type = shift; |
| 418 |
my $test = shift; |
| 419 |
|
| 420 |
return if $test; |
| 421 |
|
| 422 |
# |
| 423 |
# Carp::Datum is potentially used by many modules. Its core code |
| 424 |
# must be as small as possible to compile quickly. |
| 425 |
# |
| 426 |
# Here, we get an assertion failure, an exceptional event. It's ok |
| 427 |
# to impose a further delay. |
| 428 |
# |
| 429 |
|
| 430 |
require Carp::Datum::Assert; |
| 431 |
Carp::Datum::Assert->import(qw(assert_expr stack_dump)); |
| 432 |
|
| 433 |
my $expr = assert_expr(2); |
| 434 |
my $msg; |
| 435 |
$msg = ": " . join('', @_) if @_; |
| 436 |
$msg .= " ($expr)" if $expr ne ''; |
| 437 |
$msg = $msg . where(2); |
| 438 |
my $stack = stack_dump(2); |
| 439 |
|
| 440 |
# |
| 441 |
# When debugging, log to the debug file. |
| 442 |
# |
| 443 |
|
| 444 |
if ($DBG) { |
| 445 |
trace("$assert_type FAILED". $msg, "!!"); |
| 446 |
if ($debug_flag & DBG_STACK) { |
| 447 |
foreach my $item (@$stack) { |
| 448 |
trace($item, "!!"); |
| 449 |
} |
| 450 |
} |
| 451 |
} |
| 452 |
|
| 453 |
# |
| 454 |
# Always log something to the error channel anyway |
| 455 |
# |
| 456 |
# If they configured Log::Agent with -confess, they'll get a |
| 457 |
# stack dump as well on panic. |
| 458 |
# |
| 459 |
|
| 460 |
if ($debug_flag & DBG_PANIC) { |
| 461 |
logdie "PANIC: $assert_type FAILED" . $msg; |
| 462 |
} else { |
| 463 |
logwarn "$assert_type FAILED" . $msg; |
| 464 |
} |
| 465 |
} |
| 466 |
|
| 467 |
# |
| 468 |
# alias |
| 469 |
# |
| 470 |
# Alias filename, to strip long filenames. |
| 471 |
# |
| 472 |
sub alias { |
| 473 |
my ($name) = @_; |
| 474 |
|
| 475 |
for my $alias (@{$CFG->cfg_alias}) { |
| 476 |
my ($x, $y) = @{$alias}; |
| 477 |
if (substr($name, 0, length $x) eq $x) { |
| 478 |
substr($name, 0, length $x) = $y; |
| 479 |
last; |
| 480 |
} |
| 481 |
} |
| 482 |
|
| 483 |
return $name; |
| 484 |
} |
| 485 |
|
| 486 |
# |
| 487 |
# where |
| 488 |
# |
| 489 |
sub where { |
| 490 |
my ($level) = @_; |
| 491 |
my ($package, $filename, $line) = caller($level); |
| 492 |
$filename = alias($filename); |
| 493 |
|
| 494 |
return " [$filename:$line]"; |
| 495 |
} |
| 496 |
|
| 497 |
my $DEPTH = 0; |
| 498 |
my $max_trace_depth = -1; |
| 499 |
my $space = "| "; |
| 500 |
|
| 501 |
# |
| 502 |
# ->new |
| 503 |
# |
| 504 |
# Create a new object, meant to be destroyed at function exit |
| 505 |
# |
| 506 |
sub new { |
| 507 |
my $this = shift @_; |
| 508 |
my $class = ref($this) || $this; |
| 509 |
my $self = {}; |
| 510 |
|
| 511 |
# get the max argument setting (by specifying 'args(yes|no|num);' |
| 512 |
# in config file. |
| 513 |
# NOTE: that is done before the arg query since the call is |
| 514 |
# modifying the DB::args value with different values. |
| 515 |
my $max_arg = $CFG->flag('args', 1); |
| 516 |
|
| 517 |
my $offset = 2; |
| 518 |
my ($package, $filename, $line) = caller($offset); |
| 519 |
my $sub = (caller($offset + 1))[3]; |
| 520 |
$sub = $sub ? "$sub()" : "global"; |
| 521 |
my $from = ''; |
| 522 |
$from = " from $sub at " . alias($filename) . ":$line" if defined $line; |
| 523 |
|
| 524 |
package DB; |
| 525 |
# ignore warning |
| 526 |
use vars qw(@args); |
| 527 |
my @caller = caller(2); |
| 528 |
package Carp::Datum; |
| 529 |
|
| 530 |
# grab info from leftover parameters |
| 531 |
my $info = @_ ? ": '@_'": ""; |
| 532 |
|
| 533 |
if (@caller) { |
| 534 |
# shrink the list of argument if too long |
| 535 |
my $shrinked = 0; |
| 536 |
if ($max_arg >= 0 && $#DB::args >= $max_arg ) { |
| 537 |
$#DB::args = $max_arg - 1; |
| 538 |
$shrinked = 1; |
| 539 |
} |
| 540 |
|
| 541 |
my @args_list = map { data_format($_) } @DB::args; |
| 542 |
push @args_list, "..." if $shrinked; |
| 543 |
|
| 544 |
$self->{'call'} = "$caller[3](" . join(", ", @args_list) . ")$info"; |
| 545 |
} else { |
| 546 |
$self->{'call'} = "global$info" |
| 547 |
} |
| 548 |
$self->{'call'} .= $from; |
| 549 |
|
| 550 |
trace("+-> " . $self->{'call'} . where($offset)); |
| 551 |
$self->{'depth'} = $DEPTH++; |
| 552 |
|
| 553 |
bless $self, $class; |
| 554 |
} |
| 555 |
|
| 556 |
# |
| 557 |
# ->DESTROY |
| 558 |
# |
| 559 |
sub DESTROY { |
| 560 |
my $self = shift; |
| 561 |
|
| 562 |
my $prev_depth = $DEPTH; |
| 563 |
$DEPTH = $self->{'depth'}; |
| 564 |
trace("+-< " . $self->{'call'}); |
| 565 |
$DEPTH = $prev_depth - 1; |
| 566 |
} |
| 567 |
|
| 568 |
# |
| 569 |
# trace |
| 570 |
# |
| 571 |
sub trace { |
| 572 |
my ($message, $header) = @_; |
| 573 |
|
| 574 |
$header .= " "; |
| 575 |
$header = substr($header, 0, 3); |
| 576 |
|
| 577 |
logwrite('debug', 'debug', $header . $space x $DEPTH . $message); |
| 578 |
} |
| 579 |
|
| 580 |
# |
| 581 |
# data_format |
| 582 |
# |
| 583 |
# return the given value to a printable form. |
| 584 |
# |
| 585 |
sub data_format { |
| 586 |
return "undef" unless defined $_[0]; |
| 587 |
|
| 588 |
return $_[0] if (ref $_[0]) || ($_[0]=~ /^-?[1-9]\d{0,8}$/) || |
| 589 |
(($_[0] + 0) eq $_[0]) ; |
| 590 |
|
| 591 |
require Data::Dumper; |
| 592 |
return Data::Dumper::qquote($_[0] ); |
| 593 |
} |
| 594 |
|
| 595 |
1; |
| 596 |
|
| 597 |
=head1 NAME |
| 598 |
|
| 599 |
Carp::Datum - Debugging And Tracing Ultimate Module |
| 600 |
|
| 601 |
=head1 SYNOPSIS |
| 602 |
|
| 603 |
# In modules |
| 604 |
use Carp::Datum; |
| 605 |
|
| 606 |
# Programming by contract |
| 607 |
sub routine { |
| 608 |
DFEATURE my $f_, "optional message"; # $f_ is a lexical lvalue here |
| 609 |
my ($a, $b) = @_; |
| 610 |
DREQUIRE $a > $b, "a > b"; |
| 611 |
$a += 1; $b += 1; |
| 612 |
DASSERT $a > $b, "ordering a > b preserved"; |
| 613 |
my $result = $b - $a; |
| 614 |
DENSURE $result < 0; |
| 615 |
return DVAL $result; |
| 616 |
} |
| 617 |
|
| 618 |
# Tracing |
| 619 |
DTRACE "this is a debug message"; |
| 620 |
DTRACE TRC_NOTICE, "note: a = ", $a, " is positive"; |
| 621 |
DTRACE {-level => TRC_NOTICE, -marker => "!!"}, "note with marker"; |
| 622 |
|
| 623 |
# Returning |
| 624 |
return DVAL $scalar; # single value |
| 625 |
return DARY @list; # list of values |
| 626 |
|
| 627 |
# In application's main |
| 628 |
use Carp::Datum qw(:all on); # turns Datum "on" or "off" |
| 629 |
|
| 630 |
DLOAD_CONFIG(-file => "debug.cf", -config => "config string"); |
| 631 |
|
| 632 |
=head1 DESCRIPTION |
| 633 |
|
| 634 |
The C<Carp::Datum> module brings powerful debugging and tracing features |
| 635 |
to development code: automatic flow tracing, returned value tracing, |
| 636 |
assertions, and debugging traces. Its various functions may be customized |
| 637 |
dynamically (i.e. at run time) via a configuration language allowing |
| 638 |
selective activation on a routine, file, or object type basis. See |
| 639 |
L<Carp::Datum::Cfg> for configuration defails. |
| 640 |
|
| 641 |
C<Carp::Datum> traces are implemented on top of C<Log::Agent> and go to its |
| 642 |
debugging channel. This lets the application have full control of the |
| 643 |
final destination of the debugging information (logfile, syslog, etc...). |
| 644 |
|
| 645 |
C<Carp::Datum> can be globally turned on or off by the application. It is |
| 646 |
off by default, which means no control flow tracing (routine entry and exit), |
| 647 |
and no returned value tracing. However, assertions are still fully monitored, |
| 648 |
and the C<DTRACE> calls are redirected to C<Log::Agent>. |
| 649 |
|
| 650 |
The C version of C<Carp::Datum> is implemented with macros, which may |
| 651 |
be redefined to nothing to remove all assertions in the released |
| 652 |
code. The Perl version cannot be handled that way, but comes with |
| 653 |
a C<Carp::Datum::Strip> module that will B<lexically> remove all the |
| 654 |
assertions, leaving only C<DTRACE> calls. Modules using C<Carp::Datum> |
| 655 |
can make use of C<Carp::Datum::MakeMaker> in their Makefile.PL to |
| 656 |
request stripping at build time. See L<Carp::Datum::MakeMaker> for |
| 657 |
instructions. |
| 658 |
|
| 659 |
Here is a small example showing what traces look like, and what happens by |
| 660 |
default on assertion failure. Since C<Log::Agent> is not being customized, the |
| 661 |
debugging channel is STDERR. In real life, one would probably |
| 662 |
customize Log::Agent with a file driver, and redirect the debug channel |
| 663 |
to a file separate from both STDOUT and STDERR. |
| 664 |
|
| 665 |
First, the script, with line number: |
| 666 |
|
| 667 |
1 #!/usr/bin/perl |
| 668 |
2 |
| 669 |
3 use Carp::Datum qw(:all on); |
| 670 |
4 |
| 671 |
5 DFEATURE my $f_; |
| 672 |
6 |
| 673 |
7 show_inv(2, 0.5, 0); |
| 674 |
8 |
| 675 |
9 sub show_inv { |
| 676 |
10 DFEATURE my $f_; |
| 677 |
11 foreach (@_) { |
| 678 |
12 print "Inverse of $_ is ", inv($_), "\n"; |
| 679 |
13 } |
| 680 |
14 return DVOID; |
| 681 |
15 } |
| 682 |
16 |
| 683 |
17 sub inv { |
| 684 |
18 DFEATURE my $f_; |
| 685 |
19 my ($x) = @_; |
| 686 |
20 DREQUIRE $x != 0, "x=$x not null"; |
| 687 |
21 return DVAL 1 / $x; |
| 688 |
22 } |
| 689 |
23 |
| 690 |
|
| 691 |
What goes to STDOUT: |
| 692 |
|
| 693 |
Inverse of 2 is 0.5 |
| 694 |
Inverse of 0.5 is 2 |
| 695 |
FATAL: PANIC: pre-condition FAILED: x=0 not null ($x != 0) [./demo:20] |
| 696 |
|
| 697 |
The debugging output on STDERR: |
| 698 |
|
| 699 |
+-> global [./demo:5] |
| 700 |
| +-> main::show_inv(2, 0.5, 0) from global at ./demo:7 [./demo:10] |
| 701 |
| | +-> main::inv(2) from main::show_inv() at ./demo:12 [./demo:18] |
| 702 |
| | | Returning: (0.5) [./demo:21] |
| 703 |
| | +-< main::inv(2) from main::show_inv() at ./demo:12 |
| 704 |
| | +-> main::inv(0.5) from main::show_inv() at ./demo:12 [./demo:18] |
| 705 |
| | | Returning: (2) [./demo:21] |
| 706 |
| | +-< main::inv(0.5) from main::show_inv() at ./demo:12 |
| 707 |
| | +-> main::inv(0) from main::show_inv() at ./demo:12 [./demo:18] |
| 708 |
!! | | | pre-condition FAILED: x=0 not null ($x != 0) [./demo:20] |
| 709 |
!! | | | main::inv(0) called at ./demo line 12 |
| 710 |
!! | | | main::show_inv(2, 0.5, 0) called at ./demo line 7 |
| 711 |
** | | | FATAL: PANIC: pre-condition FAILED: x=0 not null ($x != 0) [./demo:20] |
| 712 |
| | +-< main::inv(0) from main::show_inv() at ./demo:12 |
| 713 |
| +-< main::show_inv(2, 0.5, 0) from global at ./demo:7 |
| 714 |
+-< global |
| 715 |
|
| 716 |
The last three lines were manually re-ordered for this manpage: because of the |
| 717 |
pre-condition failure, Perl enters its global object destruction routine, |
| 718 |
and the destruction order of the lexicals is not right. The $f_ in show_inv() |
| 719 |
is destroyed before the one in inv(), resulting in the inversion. To better |
| 720 |
please the eye, it has been fixed. And the PANIC is emitted when the pre-condition |
| 721 |
failure is detected, but it would have messed up the trace example. |
| 722 |
|
| 723 |
Note that the stack dump is prefixed with the "!!" token, and the fatal |
| 724 |
error is tagged with "**". This is a visual aid only, to quickly locate |
| 725 |
troubles in logfiles by catching the eye. |
| 726 |
|
| 727 |
Routine entry and exit are tagged, returned values and parameters are |
| 728 |
shown, and the immediate caller of each routine is also traced. The |
| 729 |
final tags C<from global at ./demo:7 [./demo:10]> refer to the file |
| 730 |
name (here the script used was called "demo") and the line number |
| 731 |
where the call to the C<Carp::Datum> routine is made: here the |
| 732 |
C<DFEATURE> at line 10. It also indicates the caller origin: here, the |
| 733 |
call is made at line 7 of file C<demo>. |
| 734 |
|
| 735 |
The special name "global" (without trailing () marker) is used to indicate |
| 736 |
that the caller is the main script, i.e. there is no calling routine. |
| 737 |
|
| 738 |
Returned values in inv() are traced as "(0.5)" and "(2)", and not as "0.5" |
| 739 |
and "2" as one would expect, because the routine was called in non-scalar |
| 740 |
context (within a print statement). |
| 741 |
|
| 742 |
=head1 PROGRAMMING BY CONTRACT |
| 743 |
|
| 744 |
=head2 Introduction |
| 745 |
|
| 746 |
The Programming by Contract paradigm was introduced by Bertrand Meyer in |
| 747 |
his I<Object Oriented Software Construction> book, and later implemented |
| 748 |
natively in the Eiffel language. It is very simple, yet extremely powerful. |
| 749 |
|
| 750 |
Each feature (routine) of a program is viewed externally as a supplier for |
| 751 |
some service. For instance, the sqrt() routine computes the square root |
| 752 |
of any positive number. The computation could be verified, but |
| 753 |
sqrt() probably provides an efficient algorithm for that, and it has already |
| 754 |
been written and validated. |
| 755 |
|
| 756 |
However, sqrt() is only defined for positive numbers. Giving a negative |
| 757 |
number to it is not correct. The old way (i.e. in the old days before |
| 758 |
Programming by Contract was formalized), people implemented that restriction |
| 759 |
by testing the argument I<x> of sqrt(), and doing so in the routine itself |
| 760 |
to factorize code. Then, on error, sqrt() would return -1 for instance |
| 761 |
(which cannot be a valid square root for a real number), and the desired |
| 762 |
quantity otherwise. The caller had then to check the returned value to |
| 763 |
determine whether an error had occurred. Here it is easy, but in languages |
| 764 |
where no out-of-band value such as Perl's C<undef> are implemented, it can |
| 765 |
be quite difficult to both report an error and return a result. |
| 766 |
|
| 767 |
With Programming by Contract, the logic is reversed, and the code is greatly |
| 768 |
simplified: |
| 769 |
|
| 770 |
=over 4 |
| 771 |
|
| 772 |
=item * |
| 773 |
|
| 774 |
It is up to the caller to always supply a positive value to sqrt(), i.e. to |
| 775 |
check the value first. |
| 776 |
|
| 777 |
=item * |
| 778 |
|
| 779 |
In return, sqrt() promises to always return the square root of its argument. |
| 780 |
|
| 781 |
=back |
| 782 |
|
| 783 |
What are the benefits of such a gentlemen's agreement? The code of the sqrt() |
| 784 |
routine is much simpler (meaning fewer bugs) because it does not have |
| 785 |
to bother with handling the case of negative arguments, since the caller |
| 786 |
promised to never call with such invalid values. And the code of the caller |
| 787 |
is at worst as complex as before (one test to check that the argument is |
| 788 |
positive, against a check for an error code) and at best less complex: if it is |
| 789 |
known that the value is positive, it doesn't even have to be checked, for instance |
| 790 |
if it is the result of an abs() call. |
| 791 |
|
| 792 |
But if sqrt() is called with a negative argument, and there's no explicit test |
| 793 |
in sqrt() to trap the case, what happens if sqrt() is given a negative |
| 794 |
value, despite a promise never to do so? Well, it's a bug, and it's a |
| 795 |
bug in the caller, not in the sqrt() routine. |
| 796 |
|
| 797 |
To find those bugs, one usually monitors the assertions (pre- and |
| 798 |
post-conditions, plus any other assertion in the code, which is both a |
| 799 |
post-condition for the code above and a pre-condition for the code below, |
| 800 |
at the same time) during testing. When the product is released, assertions |
| 801 |
are no longer checked. |
| 802 |
|
| 803 |
=head2 Formalism |
| 804 |
|
| 805 |
Each routine is equipped with a set of pre-conditions and post-conditions. |
| 806 |
A routine I<r> is therefore defined as: |
| 807 |
|
| 808 |
r(x) |
| 809 |
pre-condition |
| 810 |
body |
| 811 |
post-condition |
| 812 |
|
| 813 |
The pre- and post-conditions are expressions involving the parameters of r(), |
| 814 |
here only I<x>, and, for the post-condition, the returned value of r() as well. |
| 815 |
Conditions satisfying this property are made visible to the clients, and become |
| 816 |
the routine's I<contract>, which can be written as: |
| 817 |
|
| 818 |
=over 4 |
| 819 |
|
| 820 |
=item * |
| 821 |
|
| 822 |
You, the caller, promise to always call me with my pre-condition satisfied. |
| 823 |
Failure to do so will be a bug in your code. |
| 824 |
|
| 825 |
=item * |
| 826 |
|
| 827 |
I promise you, the caller, that my implementation will then perform correctly |
| 828 |
and that my post-condition will be satisfied. Failure to do so will be a |
| 829 |
bug in my code. |
| 830 |
|
| 831 |
=back |
| 832 |
|
| 833 |
In object-oriented programming, pre- and post-conditions can also use internal |
| 834 |
attributes of the object, but then become debugging checks that everything |
| 835 |
happens correctly (in the proper state, the proper order, etc...) and cannot |
| 836 |
be part of the contract (for external users of the class) since clients cannot |
| 837 |
check that the pre-condition is true, because it will not have access to the |
| 838 |
internal attributes. |
| 839 |
|
| 840 |
Furthermore, in object-oriented programming, a redefined feature must I<weaken> |
| 841 |
the pre-condition of its parent feature and I<strengthen> its post-condition. |
| 842 |
It can also keep them as-is. To fully understand why, it's best to read |
| 843 |
Meyer. Intuitively, it's easy to understand why the pre-condition cannot |
| 844 |
be strengthened, nor why the post-condition cannot be weakened: because of dynamic |
| 845 |
binding, a caller of r() only has the static type of the object, not its |
| 846 |
dynamic type. Therefore, it cannot know in advance which of the routines will |
| 847 |
be called amongst the inheritance tree. |
| 848 |
|
| 849 |
=head2 Common Pitfalls |
| 850 |
|
| 851 |
=over 4 |
| 852 |
|
| 853 |
=item * |
| 854 |
|
| 855 |
Do not write both a pre-condition and a test with the same expression. |
| 856 |
|
| 857 |
=item * |
| 858 |
|
| 859 |
Never write a pre-condition when trying to validate user input! |
| 860 |
|
| 861 |
=item * |
| 862 |
|
| 863 |
Never write a test on an argument when failure means an error, use a |
| 864 |
pre-condition. |
| 865 |
|
| 866 |
If a pre-condition is so important that it needs to always be |
| 867 |
monitored, even within the released product, then C<Carp::Datum> |
| 868 |
provides C<VERIFY>, a pre-condition that will always be checked |
| 869 |
(i.e. never stripped by C<Carp::Datum::Strip>). It can be used to protect |
| 870 |
the external interface of a module against abuse. |
| 871 |
|
| 872 |
=head2 Implementation |
| 873 |
|
| 874 |
With Carp::Datum, pre-conditions can be given using C<DREQUIRE> or C<VERIFY>. |
| 875 |
Assertions are written with C<DASSERT> and post-conditions given by C<DENSURE>. |
| 876 |
|
| 877 |
Although all assertions could be expressed with only C<DASSERT>, |
| 878 |
stating whether it's a pre-condition with C<DREQUIRE> also has |
| 879 |
a commentary value for the reader. Moreover, one day, there might be an |
| 880 |
automatic tool to extract the pre- and post-conditions of all the routines |
| 881 |
for documentation purposes, and if all assertions are called C<DASSERT>, |
| 882 |
the tool will have a hard time figuring out which is what. |
| 883 |
|
| 884 |
Moreover, remember that a pre-condition failure I<always> means a bug in the |
| 885 |
caller, whilst other assertion failures means a bug near the place of failure. |
| 886 |
If only for that, it's worth making the distinction. |
| 887 |
|
| 888 |
=back |
| 889 |
|
| 890 |
=head1 INTERFACE |
| 891 |
|
| 892 |
=head2 Control Flow |
| 893 |
|
| 894 |
=over 4 |
| 895 |
|
| 896 |
=item DFEATURE my $f_, I<optional comment> |
| 897 |
|
| 898 |
This statement marks the very top of any routine. Do not omit the C<my> |
| 899 |
which is very important to ensure that what is going to be stored in the |
| 900 |
lexically scoped $f_ variable will be destroyed when the routine ends. |
| 901 |
Any name can be used for that lexical, but $f_ is recommended because it is |
| 902 |
both unlikely to conflict with any real variable and short. |
| 903 |
|
| 904 |
The I<optional comment> part will be printed in the logs at routine entry |
| 905 |
time, and can be used to flag object constructors, for instance, for easier |
| 906 |
grep'ing in the logs afterwards. |
| 907 |
|
| 908 |
=item return DVOID |
| 909 |
|
| 910 |
This can be used in place of an ordinary C<return> from a routine. |
| 911 |
It allows tracing of the return statement. |
| 912 |
|
| 913 |
=item return DVAL I<scalar> |
| 914 |
|
| 915 |
Use this form when returning something in scalar context. Do not put any |
| 916 |
parentheses around I<scalar>, or it will be incorrectly stripped |
| 917 |
by C<Carp::Datum::Strip>. Examples: |
| 918 |
|
| 919 |
return DVAL 5; # OK |
| 920 |
return DVAL ($a == 1) ? 2 : 4; # WRONG (has parenthesis) |
| 921 |
return DVAL (1, 2, 4); # WRONG (and will return 4) |
| 922 |
|
| 923 |
my $x = ($a == 1) ? 2 : 4; |
| 924 |
return DVAL $x; # OK |
| 925 |
|
| 926 |
return DVAL &foo(); # Will be traced as array context |
| 927 |
|
| 928 |
Using DVAL allows tracing of the returned value. |
| 929 |
|
| 930 |
=item return DARY (I<list>) |
| 931 |
|
| 932 |
Use this form when returning something in list context. |
| 933 |
Using DARY allows tracing of the returned values. |
| 934 |
|
| 935 |
return DARY @x; |
| 936 |
|
| 937 |
If a routine returns something different depending on its |
| 938 |
calling context, then write: |
| 939 |
|
| 940 |
return DARY @x if wantarray; |
| 941 |
return DVAL $x; |
| 942 |
|
| 943 |
Be very careful with that, otherwise the program will behave differently |
| 944 |
when the C<DARY> and C<DVAL> tokens are stripped by C<Carp::Datum::Strip>, |
| 945 |
thereby raising subtle bugs. |
| 946 |
|
| 947 |
=back |
| 948 |
|
| 949 |
=head2 Programming by Contract |
| 950 |
|
| 951 |
=over 4 |
| 952 |
|
| 953 |
=item C<DREQUIRE> I<expr>, I<tag> |
| 954 |
|
| 955 |
Specify a pre-condition I<expr>, along with a I<tag> that will be printed |
| 956 |
whenever the pre-condition fails, i.e. when I<expr> evaluates to false. |
| 957 |
The I<tag> string may be used to dump faulty values, for instance: |
| 958 |
|
| 959 |
DREQUIRE $x > 0, "x = $x positive"; |
| 960 |
|
| 961 |
The I<tag> is optional and may be left off. |
| 962 |
|
| 963 |
=item C<VERIFY> I<expr>, I<tag> |
| 964 |
|
| 965 |
This is really the same as C<DREQUIRE>, except that it will not be stripped |
| 966 |
by C<Carp::Datum::Strip> and that it will always be monitored and cause a |
| 967 |
fatal error, whatever dynamic configuration is setup. |
| 968 |
|
| 969 |
=item C<DENSURE> I<expr>, I<tag> |
| 970 |
|
| 971 |
Specify a post-condition I<expr>, along with an optional I<tag> that will be |
| 972 |
printed whenever the post-condition fails, i.e. when I<expr> evaluates to false. |
| 973 |
|
| 974 |
=item C<DASSERT> I<expr>, I<tag> |
| 975 |
|
| 976 |
Specify an assertion I<expr>, and an optional I<tag> printed when I<expr> |
| 977 |
evaluates to false. |
| 978 |
|
| 979 |
=back |
| 980 |
|
| 981 |
=head2 Tracing |
| 982 |
|
| 983 |
Tracing is ensured by the C<DTRACE> routine, which is never stripped. When |
| 984 |
C<Carp::Datum> is off, traces are redirected to C<Log::Agent> (then channel |
| 985 |
depends on the level of the trace). |
| 986 |
|
| 987 |
The following forms can be used, from the simpler to the more complex: |
| 988 |
|
| 989 |
DTRACE "the variable x+1 is ", $x + 1, " and y is $y"; |
| 990 |
DTRACE TRC_WARNING, "a warning message"; |
| 991 |
DTRACE { -level => TRC_CRITICAL, -marker => "##" }, "very critical"; |
| 992 |
|
| 993 |
The first call emits a trace at the C<TRC_DEBUG> level, by default. The |
| 994 |
second call emits a warning at the C<TRC_WARNING> level, and the last call |
| 995 |
emits a C<TRC_CRITICAL> message prefixed with a marker. |
| 996 |
|
| 997 |
Markers are 2-char strings emitted in the very first columns of the |
| 998 |
debugging output, and can be used to put emphasis on specifice messages. |
| 999 |
Internally, C<Carp::Datum> and C<Log::Agent> use the following markers: |
| 1000 |
|
| 1001 |
!! assertion failure and stack trace |
| 1002 |
** critical errors, fatal if not trapped by eval {} |
| 1003 |
>> a message emitted via a Log::Agent routine, not DTRACE |
| 1004 |
|
| 1005 |
The table below lists the available C<TRC_> levels defined by C<Carp::Datum>, |
| 1006 |
and how they remap to C<Log::Agent> routines when C<Carp::Datum> is off: |
| 1007 |
|
| 1008 |
Carp::Datum Log::Agent |
| 1009 |
------------- ------------- |
| 1010 |
TRC_EMERGENCY logdie |
| 1011 |
TRC_ALERT logerr |
| 1012 |
TRC_CRITICAL logerr |
| 1013 |
TRC_ERROR logerr |
| 1014 |
TRC_WARNING logwarn |
| 1015 |
TRC_NOTICE logsay |
| 1016 |
TRC_INFO logtrc "info" |
| 1017 |
TRC_DEBUG logtrc "debug" |
| 1018 |
|
| 1019 |
If an application does not configure C<Log::Agent> specifically, all the calls |
| 1020 |
map nicely to perl's native routines (die, warn and print). |
| 1021 |
|
| 1022 |
=head2 Convenience Routines |
| 1023 |
|
| 1024 |
=over 4 |
| 1025 |
|
| 1026 |
=item C<equiv> I<expr1>, I<expr2> |
| 1027 |
|
| 1028 |
Returns true when both I<expr1> and I<expr2> have the same truth value, |
| 1029 |
whether they are both true or both false. |
| 1030 |
|
| 1031 |
=item C<implies> I<expr1>, I<expr2> |
| 1032 |
|
| 1033 |
Returns the truth value of I<expr1> implies I<expr2>, which is the same |
| 1034 |
as: |
| 1035 |
|
| 1036 |
!expr1 || expr2 |
| 1037 |
|
| 1038 |
It is always true except when I<expr1> is true and I<expr2> is false. |
| 1039 |
|
| 1040 |
Warning: this is function, not a macro. That is to say, both |
| 1041 |
arguments are evaluated, and there is no short-circuit when I<expr1> is false. |
| 1042 |
|
| 1043 |
=back |
| 1044 |
|
| 1045 |
=head1 DEBUG CONFIGURATION |
| 1046 |
|
| 1047 |
=head2 Global Switch on/off |
| 1048 |
|
| 1049 |
The C<Carp::Datum> module can be turned on/off. This indication must |
| 1050 |
be included when the module is imported in the main program as |
| 1051 |
followed: |
| 1052 |
|
| 1053 |
# In application's main |
| 1054 |
use Carp::Datum qw(:all on); # to turn on |
| 1055 |
use Carp::Datum qw(:all off); # to turn off |
| 1056 |
|
| 1057 |
When C<Carp::Datum> is turned off, most of the specific functions |
| 1058 |
(DFEATURE, ...) continue to be invoked during the program execution |
| 1059 |
but they return immediately. In details, all the tracing functions are |
| 1060 |
disconnected, the contracts (DASSERT, DREQUIRE, DENSURE) continue to |
| 1061 |
be verified: assertion failure will stop the program. |
| 1062 |
|
| 1063 |
That leads to a tiny perfomance loss when running production |
| 1064 |
release. But, the delivered code keeps the possibility to be easily |
| 1065 |
debugged. If the performance would be problematic in a production |
| 1066 |
release, there is a stripper program available that can extract all the |
| 1067 |
C<Carp::Datum> calls from a source file. (see L<Carp::Datum::Strip>). |
| 1068 |
|
| 1069 |
To turn on/off debugging according to an environment variable, the |
| 1070 |
module can be imported like the following: |
| 1071 |
|
| 1072 |
# In application's main |
| 1073 |
use Carp::Datum (":all", $ENV{DATUM}); |
| 1074 |
|
| 1075 |
# as a preamble to the program execution |
| 1076 |
# in your favorite shell (here /bin/ksh) |
| 1077 |
export DATUM=on # to turn on |
| 1078 |
export DATUM=off # to turn off |
| 1079 |
|
| 1080 |
=head2 Dynamic Configuration |
| 1081 |
|
| 1082 |
The dynamic configuration is loaded when the C<DLOAD_CONFIG> function |
| 1083 |
is invoked in the main program. The function signature passes |
| 1084 |
either a filename or directly a string (or both). |
| 1085 |
|
| 1086 |
DLOAD_CONFIG(-file => "./debug.cf") # filename |
| 1087 |
- or - |
| 1088 |
DLOAD_CONFIG(-config => <<EOM); # string |
| 1089 |
routine "show_inv" { |
| 1090 |
all(yes); |
| 1091 |
flow(no); |
| 1092 |
trace(no); |
| 1093 |
return(no); |
| 1094 |
} |
| 1095 |
EOM |
| 1096 |
|
| 1097 |
The syntax used in the file or the one of the config string is |
| 1098 |
described in L<Carp::Datum::Cfg>. |
| 1099 |
|
| 1100 |
The dynamic setting allows to filter the debug traces when |
| 1101 |
running. For instance, one can enforce a routine to be silent. |
| 1102 |
|
| 1103 |
As an important note, the dynamic configuration is effective only when |
| 1104 |
the global debug switch is turned on. |
| 1105 |
|
| 1106 |
=back |
| 1107 |
|
| 1108 |
=head1 LIMITATIONS |
| 1109 |
|
| 1110 |
It's not possible to insert tracing hooks like C<DFEATURE> or C<DVAL> |
| 1111 |
in stringification overloading routines. For C<DFEATURE>, that is because |
| 1112 |
the argument list might be dumped, and printing C<$self> will re-invoke |
| 1113 |
the stringification routine recursively. For C<DVAL>, this is implied by |
| 1114 |
the fact that there cannot be any C<DFEATURE> in the routine, hence C<DVAL> |
| 1115 |
cannot be used. |
| 1116 |
|
| 1117 |
=head1 BUGS |
| 1118 |
|
| 1119 |
Please report any bugs to the current maintainer. |
| 1120 |
|
| 1121 |
=head1 HISTORY AND CREDITS |
| 1122 |
|
| 1123 |
The seed of the C<Carp::Datum> module started to grow in 1996 when |
| 1124 |
Raphael Manfredi and Christophe Dehaudt were involved in a tricky |
| 1125 |
project involving kernel environment. It was Christophe's first experience |
| 1126 |
with I<Programming By Contract> principles. Raphael was already familar with |
| 1127 |
the concept due to his participation in the development of the |
| 1128 |
Eiffel compiler. |
| 1129 |
|
| 1130 |
Written in C, the first release was based on pre-processor macros. It |
| 1131 |
already distinguished the pre-conditions, post-conditions and |
| 1132 |
assertions. Also included were the concepts of dynamic configuration and |
| 1133 |
flow tracing. The benefit of this lonely include file was very |
| 1134 |
important since the final integration was very short and, since then, |
| 1135 |
there has been no major bug reported on the delivered product. |
| 1136 |
|
| 1137 |
Based on this first success, they leveraged the techniques for |
| 1138 |
developments in C++. The debug module was upgraded with the |
| 1139 |
necessary notions required for true OO programming in C++. |
| 1140 |
|
| 1141 |
The Perl module was produced in 2000, when Raphael and Christophe needed |
| 1142 |
for Perl the same powerful support that they had initiated a few years prior. |
| 1143 |
Before the first official release in spring 2001, they developed |
| 1144 |
several other Perl modules and applications (mainly related to CGI |
| 1145 |
programming) that were powered by C<Carp::Datum>. Some of them have |
| 1146 |
also been published in CPAN directory (for instance: |
| 1147 |
C<CGI::Mxscreen>). |
| 1148 |
|
| 1149 |
=head1 AUTHORS |
| 1150 |
|
| 1151 |
Christophe Dehaudt and Raphael Manfredi are the original authors. |
| 1152 |
|
| 1153 |
Send bug reports, hints, tips, suggestions to Dave Hoover at <[email protected]>. |
| 1154 |
|
| 1155 |
=head1 SEE ALSO |
| 1156 |
|
| 1157 |
Carp::Datum::Cfg(3), Carp::Datum::MakeMaker(3), Carp::Datum::Strip(3), |
| 1158 |
Log::Agent(3). |
| 1159 |
|
| 1160 |
=cut |
| 1161 |
|