lib/Data/Dumper/Concise/Sugar.pm

   1 package Data::Dumper::Concise::Sugar;
   2
   3 use 5.006;
   4
   5 our $VERSION = '2.023';
   6
   7 use Exporter ();
   8 use Data::Dumper::Concise ();
   9
  10 BEGIN { @ISA = qw(Exporter) }
  11
  12 @EXPORT = qw(
  13    $Dwarn $DwarnN Dwarn DwarnS DwarnL DwarnN DwarnF
  14    $Ddie $DdieN Ddie DdieS DdieL DdieN DdieD
  15 );
  16
  17 sub Dwarn { DwarnL(@_); return wantarray ? @_ : $_[0] }
  18
  19 our $Dwarn = \&Dwarn;
  20 our $DwarnN = \&DwarnN;
  21
  22 sub DwarnL { warn Data::Dumper::Concise::Dumper @_; @_ }
  23
  24 sub DwarnS ($) { warn Data::Dumper::Concise::Dumper $_[0]; $_[0] }
  25
  26 sub DwarnN ($) {
  27    require Devel::ArgNames;
  28    my $x = Devel::ArgNames::arg_names();
  29    warn(($x?$x:'(anon)') . ' => ' . Data::Dumper::Concise::Dumper $_[0]); $_[0]
  30 }
  31
  32 sub DwarnF (&@) { my $c = shift; warn &Data::Dumper::Concise::DumperF($c, @_); @_ }
  33
  34 sub Ddie { DdieL(@_); return wantarray ? @_ : $_[0] }
  35
  36 our $Ddie = \&Ddie;
  37 our $DdieN = \&DdieN;
  38
  39 sub DdieL { die Data::Dumper::Concise::Dumper @_ }
  40
  41 sub DdieS ($) { die Data::Dumper::Concise::Dumper $_[0] }
  42
  43 sub DdieN ($) {
  44    require Devel::ArgNames;
  45    my $x = Devel::ArgNames::arg_names();
  46    die(($x?$x:'(anon)') . ' => ' . Data::Dumper::Concise::Dumper $_[0]);
  47 }
  48
  49 =head1 NAME
  50
  51 Data::Dumper::Concise::Sugar - return Dwarn @return_value
  52
  53 =head1 SYNOPSIS
  54
  55   use Data::Dumper::Concise::Sugar;
  56
  57   return Dwarn some_call(...)
  58
  59 is equivalent to:
  60
  61   use Data::Dumper::Concise;
  62
  63   if (wantarray) {
  64      my @return = some_call(...);
  65      warn Dumper(@return);
  66      return @return;
  67   } else {
  68      my $return = some_call(...);
  69      warn Dumper($return);
  70      return $return;
  71   }
  72
  73 but shorter. If you need to force scalar context on the value,
  74
  75   use Data::Dumper::Concise::Sugar;
  76
  77   return DwarnS some_call(...)
  78
  79 is equivalent to:
  80
  81   use Data::Dumper::Concise;
  82
  83   my $return = some_call(...);
  84   warn Dumper($return);
  85   return $return;
  86
  87 If you need to force list context on the value,
  88
  89   use Data::Dumper::Concise::Sugar;
  90
  91   return DwarnL some_call(...)
  92
  93 is equivalent to:
  94
  95   use Data::Dumper::Concise;
  96
  97   my @return = some_call(...);
  98   warn Dumper(@return);
  99   return @return;
 100
 101 If you want to label your output, try DwarnN
 102
 103   use Data::Dumper::Concise::Sugar;
 104
 105   return DwarnN $foo
 106
 107 is equivalent to:
 108
 109   use Data::Dumper::Concise;
 110
 111   my @return = some_call(...);
 112   warn '$foo => ' . Dumper(@return);
 113   return @return;
 114
 115 If you want to output a reference returned by a method easily, try $Dwarn
 116
 117  $foo->bar->{baz}->$Dwarn
 118
 119 is equivalent to:
 120
 121   my $return = $foo->bar->{baz};
 122   warn Dumper($return);
 123   return $return;
 124
 125 If you want to format the output of your data structures, try DwarnF
 126
 127  my ($a, $c) = DwarnF { "awesome: $_[0] not awesome: $_[1]" } $awesome, $cheesy;
 128
 129 is equivalent to:
 130
 131   my @return = ($awesome, $cheesy);
 132   warn DumperF { "awesome: $_[0] not awesome: $_[1]" } $awesome, $cheesy;
 133   return @return;
 134
 135 If you want to immediately die after outputting the data structure, every
 136 Dwarn subroutine has a paired Ddie version, so just replace the warn with die.
 137 For example:
 138
 139  DdieL 'foo', { bar => 'baz' };
 140
 141 =head1 DESCRIPTION
 142
 143   use Data::Dumper::Concise::Sugar;
 144
 145 will import Dwarn, $Dwarn, DwarnL, DwarnN, and DwarnS into your namespace. Using
 146 L<Exporter>, so see its docs for ways to make it do something else.
 147
 148 =head2 Dwarn
 149
 150   sub Dwarn { return DwarnL(@_) if wantarray; DwarnS($_[0]) }
 151
 152 =head2 $Dwarn
 153
 154   $Dwarn = \&Dwarn
 155
 156 =head2 $DwarnN
 157
 158   $DwarnN = \&DwarnN
 159
 160 =head2 DwarnL
 161
 162   sub Dwarn { warn Data::Dumper::Concise::Dumper @_; @_ }
 163
 164 =head2 DwarnS
 165
 166   sub DwarnS ($) { warn Data::Dumper::Concise::Dumper $_[0]; $_[0] }
 167
 168 =head2 DwarnN
 169
 170   sub DwarnN { warn '$argname => ' . Data::Dumper::Concise::Dumper $_[0]; $_[0] }
 171
 172 B<Note>: this requires L<Devel::ArgNames> to be installed.
 173
 174 =head2 DwarnF
 175
 176   sub DwarnF (&@) { my $c = shift; warn &Data::Dumper::Concise::DumperF($c, @_); @_ }
 177
 178 =head1 TIPS AND TRICKS
 179
 180 =head2 global usage
 181
 182 Instead of always just doing:
 183
 184   use Data::Dumper::Concise::Sugar;
 185
 186   Dwarn ...
 187
 188 We tend to do:
 189
 190   perl -MData::Dumper::Concise::Sugar foo.pl
 191
 192 (and then in the perl code:)
 193
 194   ::Dwarn ...
 195
 196 That way, if you leave them in and run without the
 197 C<< use Data::Dumper::Concise::Sugar >> the program will fail to compile and
 198 you are less likely to check it in by accident.  Furthmore it allows that
 199 much less friction to add debug messages.
 200
 201 =head2 method chaining
 202
 203 One trick which is useful when doing method chaining is the following:
 204
 205   my $foo = Bar->new;
 206   $foo->bar->baz->Data::Dumper::Concise::Sugar::DwarnS->biff;
 207
 208 which is the same as:
 209
 210   my $foo = Bar->new;
 211   (DwarnS $foo->bar->baz)->biff;
 212
 213 =head1 SEE ALSO
 214
 215 You probably want L<Devel::Dwarn>, it's the shorter name for this module.
 216
 217 =cut
 218
 219 1;