lib/Data/Dumper/Concise.pm

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