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