Datum(3pm)

💖 NAME 💖

okay so this is the Datum(3pm) manual, and it's all about Carp::Datum — the Debugging And Tracing Ultimate Module. periodt. 💅

---

🌸 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 application's main
use Carp::Datum qw(:all on);      # turns Datum "on" or "off"

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

---

🦋 DESCRIPTION 🦋

okay so Carp::Datum is serving powerful debugging and tracing features for your development code. it's giving:

• automatic flow tracing
• returned value tracing
• assertions
• debugging traces

and the way its various functions can be customized dynamically (i.e. at run time) via a configuration language? iconic. you can selectively activate stuff 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 your application have full control of the final destination of the debugging info (logfile, syslog, etc...). 🎀

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

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. lowkey a mood. 🌈

First, the script, with line number:

 1 #!/usr/bin/perl
 2
 3 use Carp::Datum qw(:all on);
 4
 5 DFEATURE my $f_;
 6
 7 show_inv(2, 0.5, 0);
 8
 9 sub show_inv {
10      DFEATURE my $f_;
11      foreach (@_) {
12          print "Inverse of $_ is ", inv($_), "\n";
13      }
14      return DVOID;
15 }
16
17  sub inv {
18      DFEATURE my $f_;
19      my ($x) = @_;
20      DREQUIRE $x != 0, "x=$x not null";
21      return DVAL 1 / $x;
22  }
23

What goes to STDOUT:

Inverse of 2 is 0.5
Inverse of 0.5 is 2
FATAL: PANIC: pre-condition FAILED: x=0 not null ($x != 0) [./demo:20]

The debugging output on STDERR:

   +-> global [./demo:5]
   |  +-> main::show_inv(2, 0.5, 0) from global at ./demo:7 [./demo:10]
   |  |  +-> main::inv(2) from main::show_inv() at ./demo:12 [./demo:18]
   |  |  |  Returning: (0.5) [./demo:21]
   |  |  +-< main::inv(2) from main::show_inv() at ./demo:12
   |  |  +-> main::inv(0.5) from main::show_inv() at ./demo:12 [./demo:18]
   |  |  |  Returning: (2) [./demo:21]
   |  |  +-< main::inv(0.5) from main::show_inv() at ./demo:12
   |  |  +-> main::inv(0) from main::show_inv() at ./demo:12 [./demo:18]
!! |  |  |  pre-condition FAILED: x=0 not null ($x != 0) [./demo:20]
!! |  |  |  main::inv(0) called at ./demo line 12
!! |  |  |  main::show_inv(2, 0.5, 0) called at ./demo line 7
** |  |  |  FATAL: PANIC: pre-condition FAILED: x=0 not null ($x != 0) [./demo:20]
   |  |  +-< main::inv(0) from main::show_inv() at ./demo:12
   |  +-< main::show_inv(2, 0.5, 0) from global at ./demo:7
   +-< global

the last three lines were manually re-ordered for this manpage: because of the pre-condition failure, Perl enters its global object destruction routine, and the destruction order of the lexicals is not right. the $f_ in show_inv() is destroyed before the one in inv(), resulting in the inversion. to better please the eye, it has been fixed. and the PANIC is emitted when the pre-condition failure is detected, but it would have messed up the trace example. 💀

note that the stack dump is prefixed with the !! token, and the fatal error is tagged with **. this is a visual aid only, to quickly locate troubles in logfiles by catching the eye. 👀

routine entry and exit are tagged, returned values and parameters are shown, and the immediate caller of each routine is also traced. the final tags from global at ./demo:7 [./demo:10] refer to the file name (here the script used was called demo) and the line number where the call to the Carp::Datum routine is made: here the DFEATURE at line 10. it also indicates the caller origin: here, the call is made at line 7 of file demo. periodt. 💅

the special name global (without trailing () marker) is used to indicate that the caller is the main script, i.e. there is no calling routine. 🫶

returned values in inv() are traced as (0.5) and (2), and not as 0.5 and 2 as one would expect, because the routine was called in non-scalar context (within a print statement). 🤯

💖 PROGRAMMING BY CONTRACT 💖

🌸 Introduction 🌸

So Programming by Contract (PbC if you're in the group chat) was invented by Bertrand Meyer in his book Object Oriented Software Construction, and then got implemented natively in the Eiffel language. It's genuinely so simple but highkey extremely powerful. Obsessed, honestly. 💅

Here's the vibe: every feature (aka routine) of a program gets looked at from the outside like it's a supplier for some service. Take sqrt() — it computes the square root of any positive number. Like, yeah, you could verify the whole computation, but sqrt() probably has a really efficient algorithm for that, and it's already been written and validated, so why would you. ✨

But plot twist: sqrt() is only defined for positive numbers. Handing it a negative number? Not correct, bestie. Not it. So back in the day (before PbC was formalized), people handled this restriction by testing the argument x of sqrt(), doing that test inside the routine itself to factorize code. Then on error, sqrt() would return -1 (which cannot possibly be a valid square root for a real number, iykyk), and the actual desired quantity otherwise. Then the caller had to check the returned value to figure out whether an error had happened. Which is fine here, but in languages where there's no out-of-band value like Perl's undef, it can be really difficult to both report an error and return a result. 💀

With Programming by Contract, the logic gets flipped and the code is so much simpler:

• It's on the caller to always supply a positive value to sqrt(), i.e. to check the value first.
• In return, sqrt() promises to always return the square root of its argument.

So what do you actually get out of this little gentlemen's agreement? 🫶

The code of the sqrt() routine is much simpler (which means fewer bugs, periodt) because it doesn't have to bother handling negative arguments at all — the caller promised to never call with such invalid values. And the caller's code is at worst exactly as complex as before (one test to check the argument is positive, vs. a check for an error code) and at best less complex: if you already know the value is positive, you don't even have to check it — like, if it's literally the result of an abs() call. 🦋

But wait, the iconic question: if sqrt() gets called with a negative argument and there's no explicit test in sqrt() to trap that case, what even happens? Well bestie… it's a bug. And it's a bug in the caller, not in the sqrt() routine. The audacity, honestly. 😭

To find those bugs, you usually monitor the assertions during testing — that's pre- and post-conditions, plus any other assertion in the code, which is both a post-condition for the code above it and a pre-condition for the code below it, at the same time. Main character energy, fr fr. And once the product gets released, the assertions are no longer checked.

---

🎀 Formalism 🎀

Every routine gets equipped with a set of pre-conditions and post-conditions. So a routine r is defined like this:

r(x)
  pre-condition
  body
  post-condition

The pre- and post-conditions are expressions involving the parameters of r(), here just x, and — for the post-condition — the returned value of r() as well. Conditions that satisfy this property get made visible to the clients and become the routine's contract, which can be written like:

• You, the caller, promise to always call me with my pre-condition satisfied. Failure to do so will be a bug in your code.
• I promise you, the caller, that my implementation will then perform correctly and that my post-condition will be satisfied. Failure to do so will be a bug in my code.

In object-oriented programming, pre- and post-conditions can also use internal attributes of the object — but then they become debugging checks that everything happens correctly (proper state, proper order, etc...) and they cannot be part of the contract (for external users of the class), because clients can't check that the pre-condition is true — they won't have access to those internal attributes. 🚫

Also, in OOP, a redefined feature must weaken the pre-condition of its parent feature and strengthen its post-condition. It can also just keep them as-is. To fully get why, it's best to read Meyer. But intuitively it's easy to see why the pre-condition can't be strengthened and why the post-condition can't be weakened: because of dynamic binding, a caller of r() only has the static type of the object, not its dynamic type. So it literally cannot know in advance which of the routines will be called amongst the inheritance tree. 🧚

---

💀 Common Pitfalls 💀

• Do not write both a pre-condition and a test with the same expression.
• Never write a pre-condition when you're trying to validate user input!
• Never write a test on an argument when failure means an error — use a pre-condition instead.

If a pre-condition is so important that it needs to always be monitored, even within the released product, then Carp::Datum provides VERIFY — a pre-condition that will always be checked (i.e. never stripped by Carp::Datum::Strip). You can use it to protect the external interface of a module against abuse. 🛡️✨

---

👑 Implementation 👑

With Carp::Datum, pre-conditions can be given using DREQUIRE or VERIFY. Assertions get written with DASSERT, and post-conditions get given by DENSURE. 🎀

Now, technically all assertions could be expressed with only DASSERT — but stating whether it's a pre-condition with DREQUIRE also has a commentary value for whoever's reading it. Plus, one day there might be an automatic tool to extract the pre- and post-conditions of all the routines for documentation purposes, and if every assertion is just called DASSERT, that tool will have a hard time figuring out which one is which. 💅

And remember, bestie: a pre-condition failure always means a bug in the caller, whilst other assertion failures mean a bug near the place of failure. If only for that, it's so worth making the distinction. Periodt. 🌈

✨ INTERFACE ✨

🌀 Control Flow 🌀

• DFEATURE my $f_, optional comment — okay bestie, this is THE marker at the very top of any routine. Do not leave out the my — it's literally the whole point, because it makes sure whatever gets stored in the lexically scoped $f_ variable gets destroyed when the routine ends. You can name that lexical whatever you want, but $f_ is the recommended glow-up because it's short and won't beef with any real variable. The optional comment part? It gets printed in the logs when the routine starts, so you can flag object constructors and make grep'ing the logs later so much easier. 💅
• return DVOID — use this instead of a plain return from a routine. It lets you trace the return statement. Periodt.
• return DVAL scalar — use this when you're returning something in scalar context. Do not put any parentheses around scalar, or Carp::Datum::Strip will incorrectly strip them. Examples:

return DVAL 5;                      # OK
return DVAL ($a == 1) ? 2 : 4;      # WRONG (has parenthesis)
return DVAL (1, 2, 4);              # WRONG (and will return 4)

my $x = ($a == 1) ? 2 : 4;
return DVAL $x;                     # OK

return DVAL &foo();                 # Will be traced as array context

Using DVAL allows tracing of the returned value. No cap.

• return DARY (list) — use this when you're returning something in list context. DARY lets you trace the returned values.

return DARY @x;

If a routine returns something different depending on its calling context, then write:

return DARY @x if wantarray;
return DVAL $x;

Be very careful with that, otherwise the program will behave differently when the DARY and DVAL tokens are stripped by Carp::Datum::Strip, and that's how you get subtle bugs. 💀

🫶 Programming by Contract 🫶

• DREQUIRE expr, tag — specify a pre-condition expr, along with a tag that gets printed whenever the pre-condition fails (i.e. when expr evaluates to false). The tag string can dump faulty values, like:

DREQUIRE $x > 0, "x = $x positive";

The tag is optional and can be left off.

• VERIFY expr, tag — this is really the same as DREQUIRE, except it will not be stripped by Carp::Datum::Strip, and it will always be monitored and cause a fatal error, whatever dynamic configuration is set up.
• DENSURE expr, tag — specify a post-condition expr, along with an optional tag that gets printed whenever the post-condition fails (i.e. when expr evaluates to false).
• DASSERT expr, tag — specify an assertion expr, and an optional tag printed when expr evaluates to false.

🔍 Tracing 🔍

Tracing is ensured by the DTRACE routine, which is never stripped. When Carp::Datum is off, traces are redirected to Log::Agent (then channel depends on the level of the trace).

The following forms can be used, from the simpler to the more complex:

DTRACE "the variable x+1 is ", $x + 1, " and y is $y";
DTRACE TRC_WARNING, "a warning message";
DTRACE { -level => TRC_CRITICAL, -marker => "##" }, "very critical";

The first call emits a trace at the TRC_DEBUG level, by default. The second call emits a warning at the TRC_WARNING level, and the last call emits a TRC_CRITICAL message prefixed with a marker.

Markers are 2-char strings emitted in the very first columns of the debugging output, and can be used to put emphasis on specific messages. Internally, Carp::Datum and Log::Agent use the following markers:

!!    assertion failure and stack trace
**    critical errors, fatal if not trapped by eval {}
>>    a message emitted via a Log::Agent routine, not DTRACE

The table below lists the available TRC_ levels defined by Carp::Datum, and how they remap to Log::Agent routines when Carp::Datum is off:

 Carp::Datum     Log::Agent
-------------   -------------
TRC_EMERGENCY   logdie
TRC_ALERT       logerr
TRC_CRITICAL    logerr
TRC_ERROR       logerr
TRC_WARNING     logwarn
TRC_NOTICE      logsay
TRC_INFO        logtrc "info"
TRC_DEBUG       logtrc "debug"

If an application does not configure Log::Agent specifically, all the calls map nicely to perl's native routines (die, warn and print). Slay.

🌸 Convenience Routines 🌸

• equiv expr1, expr2 — returns true when both expr1 and expr2 have the same truth value, whether they are both true or both false.
• implies expr1, expr2 — returns the truth value of expr1 implies expr2, which is the same as:

!expr1 || expr2

It is always true except when expr1 is true and expr2 is false.

Warning: this is a function, not a macro. That is to say, both arguments are evaluated, and there is no short-circuit when expr1 is false. So don't get cute.

---

🎀 DEBUG CONFIGURATION 🎀

⚡ Global Switch on/off ⚡

The Carp::Datum module can be turned on/off. This indication must be included when the module is imported in the main program as followed:

# In application's main
use Carp::Datum qw(:all on);      # to turn on
use Carp::Datum qw(:all off);     # to turn off

When Carp::Datum is turned off, most of the specific functions (DFEATURE, ...) continue to be invoked during the program execution but they return immediately. In details, all the tracing functions are disconnected, the contracts (DASSERT, DREQUIRE, DENSURE) continue to be verified: assertion failure will stop the program.

That leads to a tiny performance loss when running production release. But, the delivered code keeps the possibility to be easily debugged. If the performance would be problematic in a production release, there is a stripper program available that can extract all the Carp::Datum calls from a source file. (see Carp::Datum::Strip).

To turn on/off debugging according to an environment variable, the module can be imported like the following:

# In application's main
use Carp::Datum (":all", $ENV{DATUM});

# as a preamble to the program execution
# in your favorite shell (here /bin/ksh)
export DATUM=on        # to turn on
export DATUM=off       # to turn off

🧚 Dynamic Configuration 🧚

The dynamic configuration is loaded when the DLOAD_CONFIG function is invoked in the main program. The function signature passes either a filename or directly a string (or both).

DLOAD_CONFIG(-file => "./debug.cf")  # filename
 - or -
DLOAD_CONFIG(-config => <<EOM);      # string
routine "show_inv" {
    all(yes);
    flow(no);
    trace(no);
    return(no);
}
EOM

The syntax used in the file or the one of the config string is described in Carp::Datum::Cfg.

The dynamic setting allows one to filter the debug traces when running. For instance, one can enforce a routine to be silent.

As an important note, the dynamic configuration is effective only when the global debug switch is turned on.

---

💀 LIMITATIONS 💀

It's not possible to insert tracing hooks like DFEATURE or DVAL in stringification overloading routines. For DFEATURE, that is because the argument list might be dumped, and printing $self will re-invoke the stringification routine recursively. For DVAL, this is implied by the fact that there cannot be any DFEATURE in the routine, hence DVAL cannot be used.

🐛 BUGS 🐛

Please report any bugs to the current maintainer.

📜 HISTORY AND CREDITS 📜

The seed of the Carp::Datum module started to grow in 1996 when Raphael Manfredi and Christophe Dehaudt were involved in a tricky project involving kernel environment. It was Christophe's first experience with Programming By Contract principles. Raphael was already familiar with the concept due to his participation in the development of the Eiffel compiler.

Written in C, the first release was based on pre-processor macros. It already distinguished the pre-conditions, post-conditions and assertions. Also included were the concepts of dynamic configuration and flow tracing. The benefit of this lonely include file was very important since the final integration was very short and, since then, there has been no major bug reported on the delivered product.

Based on this first success, they leveraged the techniques for developments in C++. The debug module was upgraded with the necessary notions required for true OO programming in C++.

The Perl module was produced in 2000, when Raphael and Christophe needed for Perl the same powerful support that they had initiated a few years prior. Before the first official release in spring 2001, they developed several other Perl modules and applications (mainly related to CGI programming) that were powered by Carp::Datum. Some of them have also been published in CPAN directory (for instance: CGI::Mxscreen).

👑 AUTHORS 👑

Christophe Dehaudt and Raphael Manfredi are the original authors.

Send bug reports, hints, tips, suggestions to Dave Hoover at <squirrel@cpan.org>.

🌈 SEE ALSO 🌈

Carp::Datum::Cfg(3), Carp::Datum::MakeMaker(3), Carp::Datum::Strip(3), Log::Agent(3).

---

And that's the whole vibe. This was Datum(3pm) from perl v5.34.0, dated 2022-06-30. Stay iconic, bestie. 💖✨