Devel::DDCWarn(3pm)

💖 Devel::DDCWarn 💖

ok bestie so you know how Devel::Dwarn exists? this is literally that, but for Data::Dumper::Compact. it's a Perl module (the 3pm kind, we're fancy like that) and it's about to make your printf-debugging era iconic. 🎀

---

✨ SYNOPSIS ✨

like, the whole vibe in four lines:

use Devel::DDCWarn;

my $x = Dwarn some_sub_call(); # warns and returns value
my @y = Derr other_sub_call(); # prints to STDERR and returns value

my $x = DwarnT X => some_sub_call(); # warns with tag 'X' and returns value
my @y = DerrT X => other_sub_call(); # similar

no cap, that's it. that's the whole pitch. 💅

---

🌸 DESCRIPTION 🌸

so Devel::DDCWarn is the Devel::Dwarn equivalent for Data::Dumper::Compact. it's giving... the same energy, new outfit.

the idea, basically — and say it with me — is that it is incredibly annoying to start off with code like this:

return some_sub_call();

and then realise you need the value, so you have to write:

my @ret = some_sub_call();
warn Dumper [ THE_THING => @ret ];
return @ret;

ugh. the chores. not the main character energy we're going for. 🙈

with Devel::DDCWarn, you can instead write:

return DwarnT THE_THING => some_sub_call();

and expect it to Just Work. periodt. ✨

and when you want to integrate with your logging, you can do:

our $L = sub { $log->debug("DDC debugging: ".$_[0] };
...
return DtoT $L, THE_THING => some_sub_call();

also, when you're doing the printf debugging style approaches, it is very useful to be able to do:

perl -MDevel::DDCwarn ...

and then, within the code being debugged, abuse the fact that a prefix of :: is short for main::, so we can add:

return ::DwarnT THE_THING => some_sub_call();

and if we forget to remove them, the lack of command-line Devel::DDCWarn exported into main:: will produce a compile time failure. which is, honestly, exceedingly useful — it's the module doing a vibe check on your commit. you get to notice you forgot to remove a debug statement before you commit it along with the test and fix. chef's kiss. 👑

---

💜 EXPORTS 💜

all of these subroutines are exported by default. no :all tag drama, they just show up. 🫶

quick note bestie: Data::Dumper::Compact is referred to herein as DDC.

🌈 Dwarn

my $x = Dwarn make_x();
my @y = Dwarn make_y_array();

warn()s the Df DDC dump of its input, then returns the first element in scalar context, or all arguments in list context. so it yells and hands you the thing back. 💖

🦋 Derr

my $x = Derr make_x();
my @y = Derr make_y_array();

prints the Df DDC dump of its input to STDERR, then returns the first element in scalar context, or all arguments in list context. same deal, different stream. 📤

⭐ DwarnT

my $x = Dwarn TAG => make_x();
my @y = Dwarn TAG => make_y_array();

like Dwarn, but it passes its first argument, the tag, through to DfT — and then skips it for the return value. so the tag is for the output only, it does not come back to haunt you. 💫

🌸 DerrT

my $x = Derr TAG => make_x();
my @y = Derr TAG => make_y_array();

like Derr, but it accepts a tag argument that is included in the output but is skipped for the return value. same tag energy, STDERR delivery. 🎀

🧚 Dto

Dto(sub { warn $_[0] }, @args);

like Dwarn, but instead of warning, it calls the subroutine passed as the first argument — this function is low level, but it still returns the @args. it's the pluggable one, the "you pick what happens" one. 🔌

💅 DtoT

DtoT(sub { err $_[0] }, $tag, @args);

the tagged version of Dto. tag goes in, tag does not come back. ✨

🌈 Df

my $x = Df($thing);
my $y = Df(@other_things);

a single value is returned formatted by DDC. multiple values are transformed to a DDC list. simple, clean, slay. 💖

👑 DfT

my $x = Df($tag => $thing);
my $y = Df($tag => @other_things);

a tag plus a single value is formatted as a two element list. a tag plus multiple values is formatted as a list containing the tag and a list of the values.

and here's the spicy part: if the tag is an arrayref, it is assumed to be:

my $x = Df([ $tag, $tweak ] => @things);

and what's dumped is "<$tweak-"(@things)>> instead of @things. this means that, e.g., one can write:

return Dwarn([ foo => sub { +{ @_ } } ], %things);

to output the things as a hashref while still returning a flattened hash. best of both worlds, no tradeoffs, we love to see it. 🔥

---

🎀 CONFIGURATION 🎀

use Devel::DDCWarn \%options, ...;

perl -MDevel::DDCWarn=-optname,value,-other,value ...;

$Devel::DDCWarn::ddc = Data::Dumper::Compact->new(\%options);

options passed as a hashref on a use line, or using - prefixing on the command line, are used to initialise the Data::Dumper::Compact object. so you can customise the drip from either direction. 💅

⚠️ heads up bestie: this is primarily a debugging and/or scripting oriented tool, so if something initialises us again later, this will reset the (single) global $ddc used by this code and change all output through the process. that's the deal. it's global global. 🌍

however! if you need a localised change of formatting style, $ddc is a full fledged global, so you are absolutely allowed to local it:

my $ddc = Data::Dumper::Compact->new(\%my_local_options);
local $Devel::DDCWarn::ddc = $ddc;

and if you have a convincing reason for using this functionality in a way where the globality is a bug rather than a feature — please start a conversation with the authors so we can figure out what to do about it. they're nice, fr fr. 🫶

---

💖 COPYRIGHT 💖

copyright (c) 2019 the AUTHOR in Data::Dumper::Compact and CONTRIBUTORS in Data::Dumper::Compact as listed in Data::Dumper::Compact. giving credit where credit is due, always. 🌟

---

🌈 LICENSE 🌈

this library is free software and may be distributed under the same terms as perl itself. see <https://dev.perl.org/licenses/>. free as in go forth and debug, bestie. 🦋

---

ok that's the whole page, mwah 💋 — this was Devel::DDCWarn(3pm), documented for perl v5.36.0 and dated 2022-10-04. go forth, warn responsibly, and remember to delete your debug statements before you commit. not me reminding you again. 😭💖