Debian Codegraph @

README

raw
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 ========================================================================
17 This module is known to exercise a bug in perl 5.6.0. Don't use that
18 version of perl: use 5.005_03, or try 5.6.1.
19
20 If 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
25 Name DSLI Description Info
26 ----------- ---- -------------------------------------------- -----
27 Carp::Datum adpf Debugging And Tracing Ultimate Module CDE
28
29 ========================================================================
30
31 This module is the Perl version of a C/C++ library, called DATUM, which
32 Christophe Dehaudt & Raphael Manfredi used in many programs since 1996.
33
34 Following is the preamble to the DATUM library, written by Raphael in 1998:
35
36 --- Begin Exerpt:
37
38 A bug in a software system may have multiple causes. It can be the result
39 of an oversight, a typo, a misunderstanding, a misuse, etc... Being able
40 to identify the presence of a bug, and then nail it down as quickly as
41 possible were the reasons of our deciding to create debugging foundations.
42
43 During the bug hunting phase, a developer needs to be able to trace
44 routine execution around the suspected bug spot, which is a moving target
45 usually. Flexibility of the tracing subsystem is therefore mandatory to
46 only be able to trace a specific area of the software.
47
48 Detecting bugs as early as possible is also recognized as the most
49 efficient route to quality, and it is certainly economically justified.
50 By following the Design by Contract principle, i.e. by inserting pre- and
51 post-conditions to specify the interfaces, one guards against improper
52 implementations and also formally documents the original intent of the
53 designer. That is also an invaluable aid during maintenance or evolution,
54 since it avoids improper use of existing interfaces that could otherwise
55 lead 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
67 Carp::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
77 In 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
83 A sepcial precondition, VERIFY, is always kept (i.e. never stripped)
84 and can be used for checking important conditions, to write:
85
86 VERIFY $pre_condition, "message";
87
88 where one would otherwise use a test like:
89
90 logcroak "message" if !$pre_condition;
91
92 in regular code.
93
94 Over the years, the original authors found DATUM to be a very valuable
95 aid in large software, especially in situations where the bug tolerence
96 is zero: OS modules, DB access/replication modules.
97
98 Send bug reports, hints, tips, suggestions to Dave Hoover at
99 <[email protected]>.