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