README
1 Carp::Datum 0.1
2 Copyright (c) 2002, Dave Hoover
3 Copyright (c) 2000-2001, Christophe Dehaudt & Raphael Manfredi
4
5------------------------------------------------------------------------
6 This program is free software; you can redistribute it and/or modify
7 it under the terms of the Artistic License, a copy of which can be
8 found with perl.
9
10 This program is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 Artistic License for more details.
14------------------------------------------------------------------------
15
16========================================================================
17This module is known to exercise a bug in perl 5.6.0. Don't use that
18version of perl: use 5.005_03, or try 5.6.1.
19
20If ran under 5.6.0 nonetheless, the t/failmsg_on tests will be skipped.
21========================================================================
22
23 *** This is alpha software -- use at your own risks ***
24
25Name DSLI Description Info
26----------- ---- -------------------------------------------- -----
27Carp::Datum adpf Debugging And Tracing Ultimate Module CDE
28
29========================================================================
30
31This module is the Perl version of a C/C++ library, called DATUM, which
32Christophe Dehaudt & Raphael Manfredi used in many programs since 1996.
33
34Following is the preamble to the DATUM library, written by Raphael in 1998:
35
36--- Begin Exerpt:
37
38A bug in a software system may have multiple causes. It can be the result
39of an oversight, a typo, a misunderstanding, a misuse, etc... Being able
40to identify the presence of a bug, and then nail it down as quickly as
41possible were the reasons of our deciding to create debugging foundations.
42
43During the bug hunting phase, a developer needs to be able to trace
44routine execution around the suspected bug spot, which is a moving target
45usually. Flexibility of the tracing subsystem is therefore mandatory to
46only be able to trace a specific area of the software.
47
48Detecting bugs as early as possible is also recognized as the most
49efficient route to quality, and it is certainly economically justified.
50By following the Design by Contract principle, i.e. by inserting pre- and
51post-conditions to specify the interfaces, one guards against improper
52implementations and also formally documents the original intent of the
53designer. That is also an invaluable aid during maintenance or evolution,
54since it avoids improper use of existing interfaces that could otherwise
55lead to havoc when left undetected.
56
57
58 NOTE: It is a wise practice to develop and test a piece of
59 software with all the assertions turned on (that includes pre- and
60 post-conditions, but also any additional assertion checking within
61 the code), and release it with only pre-conditions enabled. Indeed,
62 software correctness is compromised when any pre-condition is
63 violated.
64
65--- End Exerpt.
66
67Carp::Datum implements the following features:
68
69* Programming by contract: pre-conditions, post-conditions, assertions.
70* Flow control tracing: routine entry, arguments, returned values
71* Dynamic (i.e. runtime) configuration via mini language to tailor
72 debugging and/or tracing at the routine / file / package / type level.
73* Ability to statically remove all assertions and flow control tracing
74 hooks in modules making use of Carp::Datum.
75* Cooperation with Log::Agent for tracing.
76
77In order to do so, the following routines are provided:
78
79 Assertions: DREQUIRE, DENSURE, DASSERT
80 Flow control: DFEATURE, DVAL, DARY, DVOID
81 Tracing: DTRACE
82
83A sepcial precondition, VERIFY, is always kept (i.e. never stripped)
84and can be used for checking important conditions, to write:
85
86 VERIFY $pre_condition, "message";
87
88where one would otherwise use a test like:
89
90 logcroak "message" if !$pre_condition;
91
92in regular code.
93
94Over the years, the original authors found DATUM to be a very valuable
95aid in large software, especially in situations where the bug tolerence
96is zero: OS modules, DB access/replication modules.
97
98Send bug reports, hints, tips, suggestions to Dave Hoover at
99<squirrel@cpan.org>.
100