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