NAME

       Devel::DDCWarn - Easy printf-style debugging with Data::Dumper::Compact

SYNOPSIS

         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

DESCRIPTION

       Devel::DDCWarn is a Devel::Dwarn equivalent for Data::Dumper::Compact.

       The idea, basically, is that it's 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;

       With Devel::DDCWarn, one can instead write:

         return DwarnT THE_THING => some_sub_call();

       and expect it to Just Work.

       To integrate with your logging, you can do:

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

       When applying printf debugging style approaches, it's also very useful to be able to do:

         perl -MDevel::DDCwarn ...

       and then within the code being debugged, abusing 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. This is exceedingly useful for noticing you
       forgot to remove a debug statement before you commit it along with the test and fix.

EXPORTS

       All of these subroutines are exported by default.

       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.

   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.

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

       Like "Dwarn", but passes its first argument, the tag, through to "DfT" but skips it for
       the return value.

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

       Like "Derr", but accepts a tag argument that is included in the output but is skipped for
       the return value.

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

       Like "Dwarn", but instead of warning, calls the subroutine passed as the first argument -
       this function is low level but still returns the @args.

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

       The tagged version of Dto.

   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.

   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.

       If the tag is an arrayref, 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.

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.

       Note that this primarily being a debugging and/or scripting oriented tool, if something
       initialises us again later, this will reset the (single) global $ddc used by this code and
       change all output through the process.

       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;

       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.

COPYRIGHT

       Copyright (c) 2019 the "AUTHOR" in Data::Dumper::Compact and "CONTRIBUTORS" in
       Data::Dumper::Compact as listed in Data::Dumper::Compact.

LICENSE

       This library is free software and may be distributed under the same terms as perl itself.
       See <https://dev.perl.org/licenses/>.