Carp::Datum 0.1 Copyright (c) 2000-2001, Christophe Dehaudt & Raphael Manfredi ------------------------------------------------------------------------ This program is free software; you can redistribute it and/or modify it under the terms of the Artistic License, a copy of which can be found with perl. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the Artistic License for more details. ------------------------------------------------------------------------ ======================================================================== This module is known to exercise a bug in perl 5.6.0. Don't use that version of perl: use 5.005_03, or try 5.6.1. If ran under 5.6.0 nonetheless, the t/failmsg_on tests will be skipped. ======================================================================== *** This is alpha software -- use at your own risks *** Name DSLI Description Info ----------- ---- -------------------------------------------- ----- Carp::Datum adpf Debugging And Tracing Ultimate Module CDE ======================================================================== This module is the Perl version of a C/C++ library, called DATUM, which we have been using in many programs since 1996. Following is the preamble to the DATUM library, written by Raphael in 1998: --- Begin Exerpt: A bug in a software system may have multiple causes. It can be the result of an oversight, a typo, a misunderstanding, a misuse, etc... Being able to identify the presence of a bug, and then nail it down as quickly as possible were the reasons of our deciding to create debugging foundations. During the bug hunting phase, a developer needs to be able to trace routine execution around the suspected bug spot, which is a moving target usually. Flexibility of the tracing subsystem is therefore mandatory to only be able to trace a specific area of the software. Detecting bugs as early as possible is also recognized as the most efficient route to quality, and it is certainly economically justified. By following the Design by Contract principle, i.e. by inserting pre- and post-conditions to specify the interfaces, one guards against improper implementations and also formally documents the original intent of the designer. That is also an invaluable aid during maintenance or evolution, since it avoids improper use of existing interfaces that could otherwise lead to havoc when left undetected. NOTE: It is a wise practice to develop and test a piece of software with all the assertions turned on (that includes pre- and post-conditions, but also any additional assertion checking within the code), and release it with only pre-conditions enabled. Indeed, software correctness is compromised when any pre-condition is violated. --- End Exerpt. Carp::Datum implements the following features: * Programming by contract: pre-conditions, post-conditions, assertions. * Flow control tracing: routine entry, arguments, returned values * Dynamic (i.e. runtime) configuration via mini language to tailor debugging and/or tracing at the routine / file / package / type level. * Ability to statically remove all assertions and flow control tracing hooks in modules making use of Carp::Datum. * Cooperation with Log::Agent for tracing. In order to do so, the following routines are provided: Assertions: DREQUIRE, DENSURE, DASSERT Flow control: DFEATURE, DVAL, DARY, DVOID Tracing: DTRACE A sepcial precondition, VERIFY, is always kept (i.e. never stripped) and can be used for checking important conditions, to write: VERIFY $pre_condition, "message"; where one would otherwise use a test like: logcroak "message" if !$pre_condition; in regular code. Over the years, we have found DATUM to be a very valuable aid in large software, especially in situations where the bug tolerence is zero: OS modules, DB access/replication modules. We hope you will enjoy it. -- Christophe Dehaudt -- Raphael Manfredi