lib/Data/Dumper/Concise.pm

   1 package Data::Dumper::Concise;
   2
   3 use 5.006;
   4
   5 $VERSION = '2.020';
   6
   7 require Exporter;
   8 require Data::Dumper;
   9 use Scalar::Util 'isweak';
  10
  11 BEGIN { @ISA = qw(Exporter) }
  12
  13 @EXPORT = qw(Dumper DumperF DumperObject);
  14
  15 sub DumperObject {
  16   my $dd = Data::Dumper->new([]);
  17   $dd->Terse(1)->Indent(1)->Useqq(1)->Deparse(1)->Quotekeys(0)->Sortkeys(1);
  18 }
  19
  20 sub Dumper {
  21    my $o = Data::Dumper->can('_dump');
  22    local *Data::Dumper::_dump = sub {
  23       isweak($_[1])
  24          ? 'do { WEAK: ' . $o->(@_) . ' }'
  25          : $o->(@_)
  26    };
  27    DumperObject->Values([ @_ ])->Dump
  28 }
  29
  30 sub DumperF (&@) {
  31   my $code = shift;
  32   return $code->(map Dumper($_), @_);
  33 }
  34
  35 =head1 NAME
  36
  37 Data::Dumper::Concise - Less indentation and newlines plus sub deparsing
  38
  39 =head1 SYNOPSIS
  40
  41   use Data::Dumper::Concise;
  42
  43   warn Dumper($var);
  44
  45 is equivalent to:
  46
  47   use Data::Dumper;
  48   {
  49     local $Data::Dumper::Terse = 1;
  50     local $Data::Dumper::Indent = 1;
  51     local $Data::Dumper::Useqq = 1;
  52     local $Data::Dumper::Deparse = 1;
  53     local $Data::Dumper::Quotekeys = 0;
  54     local $Data::Dumper::Sortkeys = 1;
  55     warn Dumper($var);
  56   }
  57
  58 So for the structure:
  59
  60   { foo => "bar\nbaz", quux => sub { "fleem" } };
  61
  62 Data::Dumper::Concise will give you:
  63
  64   {
  65     foo => "bar\nbaz",
  66     quux => sub {
  67         use warnings;
  68         use strict 'refs';
  69         'fleem';
  70     }
  71   }
  72
  73 instead of the default Data::Dumper output:
  74
  75   $VAR1 = {
  76    'quux' => sub { "DUMMY" },
  77    'foo' => 'bar
  78   baz'
  79   };
  80
  81 (note the tab indentation, oh joy ...)
  82
  83 If you need to get the underlying L<Dumper> object just call C<DumperObject>.
  84
  85 Also try out C<DumperF> which takes a C<CodeRef> as the first argument to
  86 format the output.  For example:
  87
  88   use Data::Dumper::Concise;
  89
  90   warn DumperF { "result: $_[0] result2: $_[1]" } $foo, $bar;
  91
  92 Which is the same as:
  93
  94   warn 'result: ' . Dumper($foo) . ' result2: ' . Dumper($bar);
  95
  96 =head1 DESCRIPTION
  97
  98 This module always exports a single function, Dumper, which can be called
  99 with an array of values to dump those values.
 100
 101 It exists, fundamentally, as a convenient way to reproduce a set of Dumper
 102 options that we've found ourselves using across large numbers of applications,
 103 primarily for debugging output.
 104
 105 The principle guiding theme is "all the concision you can get while still
 106 having a useful dump and not doing anything cleverer than setting Data::Dumper
 107 options" - it's been pointed out to us that Data::Dump::Streamer can produce
 108 shorter output with less lines of code. We know. This is simpler and we've
 109 never seen it segfault. But for complex/weird structures, it generally rocks.
 110 You should use it as well, when Concise is underkill. We do.
 111
 112 Why is deparsing on when the aim is concision? Because you often want to know
 113 what subroutine refs you have when debugging and because if you were planning
 114 to eval this back in you probably wanted to remove subrefs first and add them
 115 back in a custom way anyway. Note that this -does- force using the pure perl
 116 Dumper rather than the XS one, but I've never in my life seen Data::Dumper
 117 show up in a profile so "who cares?".
 118
 119 =head1 BUT BUT BUT ...
 120
 121 Yes, we know. Consider this module in the ::Tiny spirit and feel free to
 122 write a Data::Dumper::Concise::ButWithExtraTwiddlyBits if it makes you
 123 happy. Then tell us so we can add it to the see also section.
 124
 125 =head1 SUGARY SYNTAX
 126
 127 This package also provides:
 128
 129 L<Data::Dumper::Concise::Sugar> - provides Dwarn and DwarnS convenience functions
 130
 131 L<Devel::Dwarn> - shorter form for Data::Dumper::Concise::Sugar
 132
 133 =head1 SEE ALSO
 134
 135 We use for some purposes, and dearly love, the following alternatives:
 136
 137 L<Data::Dump> - prettiness oriented but not amazingly configurable
 138
 139 L<Data::Dump::Streamer> - brilliant. beautiful. insane. extensive. excessive. try it.
 140
 141 L<JSON::XS> - no, really. If it's just plain data, JSON is a great option.
 142
 143 =head1 AUTHOR
 144
 145 mst - Matt S. Trout <mst@shadowcat.co.uk>
 146
 147 =head1 CONTRIBUTORS
 148
 149 frew - Arthur Axel "fREW" Schmidt <frioux@gmail.com>
 150
 151 =head1 COPYRIGHT
 152
 153 Copyright (c) 2010 the Data::Dumper::Concise L</AUTHOR> and L</CONTRIBUTORS>
 154 as listed above.
 155
 156 =head1 LICENSE
 157
 158 This library is free software and may be distributed under the same terms
 159 as perl itself.
 160
 161 =cut
 162
 163 1;