lib/Data/Dumper/Concise/Sugar.pm

   1 package Data::Dumper::Concise::Sugar;
   2
   3 use 5.006;
   4
   5 use Exporter ();
   6 use Data::Dumper::Concise ();
   7 use Devel::ArgNames;
   8
   9 BEGIN { @ISA = qw(Exporter) }
  10
  11 @EXPORT = qw($Dwarn Dwarn DwarnS DwarnL DwarnN);
  12
  13 sub Dwarn { return DwarnL(@_) if wantarray; DwarnS($_[0]) }
  14
  15 our $Dwarn = \&Dwarn;
  16
  17 sub DwarnL { warn Data::Dumper::Concise::Dumper @_; @_ }
  18
  19 sub DwarnS ($) { warn Data::Dumper::Concise::Dumper $_[0]; $_[0] }
  20
  21 sub DwarnN ($) {
  22    my $x = arg_names();
  23    warn(($x?$x:'(anon)') . ' => ' . Data::Dumper::Concise::Dumper $_[0]); $_[0]
  24 }
  25
  26 =head1 NAME
  27
  28 Data::Dumper::Concise::Sugar - return Dwarn @return_value
  29
  30 =head1 SYNOPSIS
  31
  32   use Data::Dumper::Concise::Sugar;
  33
  34   return Dwarn some_call(...)
  35
  36 is equivalent to:
  37
  38   use Data::Dumper::Concise;
  39
  40   if (wantarray) {
  41      my @return = some_call(...);
  42      warn Dumper(@return);
  43      return @return;
  44   } else {
  45      my $return = some_call(...);
  46      warn Dumper($return);
  47      return $return;
  48   }
  49
  50 but shorter. If you need to force scalar context on the value,
  51
  52   use Data::Dumper::Concise::Sugar;
  53
  54   return DwarnS some_call(...)
  55
  56 is equivalent to:
  57
  58   use Data::Dumper::Concise;
  59
  60   my $return = some_call(...);
  61   warn Dumper($return);
  62   return $return;
  63
  64 If you need to force list context on the value,
  65
  66   use Data::Dumper::Concise::Sugar;
  67
  68   return DwarnL some_call(...)
  69
  70 is equivalent to:
  71
  72   use Data::Dumper::Concise;
  73
  74   my @return = some_call(...);
  75   warn Dumper(@return);
  76   return @return;
  77
  78 If you want to label your output, try DwarnN
  79
  80   use Data::Dumper::Concise::Sugar;
  81
  82   return DwarnN $foo
  83
  84 is equivalent to:
  85
  86   use Data::Dumper::Concise;
  87
  88   my @return = some_call(...);
  89   warn '$foo => ' . Dumper(@return);
  90   return @return;
  91
  92 If you want to output a reference returned by a method easily, try $Dwarn
  93
  94  $foo->bar->{baz}->$Dwarn
  95
  96 is equivalent to:
  97
  98   my $return = $foo->bar->{baz};
  99   warn Dumper($return);
 100   return $return;
 101
 102 =head1 DESCRIPTION
 103
 104   use Data::Dumper::Concise::Sugar;
 105
 106 will import Dwarn, $Dwarn, DwarnL, DwarnN, and DwarnS into your namespace. Using
 107 L<Exporter>, so see its docs for ways to make it do something else.
 108
 109 =head2 Dwarn
 110
 111   sub Dwarn { return DwarnL(@_) if wantarray; DwarnS($_[0]) }
 112
 113 =head2 $Dwarn
 114
 115   $Dwarn = \&Dwarn
 116
 117 =head2 DwarnL
 118
 119   sub Dwarn { warn Data::Dumper::Concise::Dumper @_; @_ }
 120
 121 =head2 DwarnS
 122
 123   sub DwarnS ($) { warn Data::Dumper::Concise::Dumper $_[0]; $_[0] }
 124
 125 =head2 DwarnN
 126
 127   sub DwarnN { warn '$argname => ' . Data::Dumper::Concise::Dumper $_[0]; $_[0] }
 128
 129 =head1 TIPS AND TRICKS
 130
 131 =head2 global usage
 132
 133 Instead of always just doing:
 134
 135   use Data::Dumper::Concise::Sugar;
 136
 137   Dwarn ...
 138
 139 We tend to do:
 140
 141   perl -MData::Dumper::Concise::Sugar foo.pl
 142
 143 (and then in the perl code:)
 144
 145   ::Dwarn ...
 146
 147 That way, if you leave them in and run without the
 148 C<< use Data::Dumper::Concise::Sugar >> the program will fail to compile and
 149 you are less likely to check it in by accident.  Furthmore it allows that
 150 much less friction to add debug messages.
 151
 152 =head2 method chaining
 153
 154 One trick which is useful when doing method chaining is the following:
 155
 156   my $foo = Bar->new;
 157   $foo->bar->baz->Data::Dumper::Concise::Sugar::DwarnS->biff;
 158
 159 which is the same as:
 160
 161   my $foo = Bar->new;
 162   (DwarnS $foo->bar->baz)->biff;
 163
 164 =head1 SEE ALSO
 165
 166 You probably want L<Devel::Dwarn>, it's the shorter name for this module.
 167
 168 =cut
 169
 170 1;