Initial Commit

database/perl/vendor/lib/Data/Dumper/Concise.pm

@@ -0,0 +1,161 @@
+package Data::Dumper::Concise;
+
+use 5.006;
+
+our $VERSION = '2.023';
+
+require Exporter;
+require Data::Dumper;
+
+BEGIN { @ISA = qw(Exporter) }
+
+@EXPORT = qw(Dumper DumperF DumperObject);
+
+sub DumperObject {
+  my $dd = Data::Dumper->new([]);
+  $dd->Trailingcomma(1) if $dd->can('Trailingcomma');
+  $dd->Terse(1)->Indent(1)->Useqq(1)->Deparse(1)->Quotekeys(0)->Sortkeys(1);
+}
+
+sub Dumper { DumperObject->Values([ @_ ])->Dump }
+
+sub DumperF (&@) {
+  my $code = shift;
+  return $code->(map Dumper($_), @_);
+}
+
+=head1 NAME
+
+Data::Dumper::Concise - Less indentation and newlines plus sub deparsing
+
+=head1 SYNOPSIS
+
+  use Data::Dumper::Concise;
+
+  warn Dumper($var);
+
+is equivalent to:
+
+  use Data::Dumper;
+  {
+    local $Data::Dumper::Terse = 1;
+    local $Data::Dumper::Indent = 1;
+    local $Data::Dumper::Useqq = 1;
+    local $Data::Dumper::Deparse = 1;
+    local $Data::Dumper::Quotekeys = 0;
+    local $Data::Dumper::Sortkeys = 1;
+    local $Data::Dumper::Trailingcomma = 1;
+    warn Dumper($var);
+  }
+
+So for the structure:
+
+  { foo => "bar\nbaz", quux => sub { "fleem" } };
+
+Data::Dumper::Concise will give you:
+
+  {
+    foo => "bar\nbaz",
+    quux => sub {
+        use warnings;
+        use strict 'refs';
+        'fleem';
+    },
+  }
+
+instead of the default Data::Dumper output:
+
+  $VAR1 = {
+   'quux' => sub { "DUMMY" },
+   'foo' => 'bar
+  baz'
+  };
+
+(note the tab indentation, oh joy ...)
+
+(The trailing comma on the last element of an array or hash is enabled by a new
+feature in Data::Dumper version 2.159, which was first released in Perl 5.24.
+Using Data::Dumper::Concise with an older version of Data::Dumper will still
+work, but you won't get those commas.)
+
+If you need to get the underlying L<Dumper> object just call C<DumperObject>.
+
+Also try out C<DumperF> which takes a C<CodeRef> as the first argument to
+format the output.  For example:
+
+  use Data::Dumper::Concise;
+
+  warn DumperF { "result: $_[0] result2: $_[1]" } $foo, $bar;
+
+Which is the same as:
+
+  warn 'result: ' . Dumper($foo) . ' result2: ' . Dumper($bar);
+
+=head1 DESCRIPTION
+
+This module always exports a single function, Dumper, which can be called
+with an array of values to dump those values.
+
+It exists, fundamentally, as a convenient way to reproduce a set of Dumper
+options that we've found ourselves using across large numbers of applications,
+primarily for debugging output.
+
+The principle guiding theme is "all the concision you can get while still
+having a useful dump and not doing anything cleverer than setting Data::Dumper
+options" - it's been pointed out to us that Data::Dump::Streamer can produce
+shorter output with less lines of code. We know. This is simpler and we've
+never seen it segfault. But for complex/weird structures, it generally rocks.
+You should use it as well, when Concise is underkill. We do.
+
+Why is deparsing on when the aim is concision? Because you often want to know
+what subroutine refs you have when debugging and because if you were planning
+to eval this back in you probably wanted to remove subrefs first and add them
+back in a custom way anyway. Note that this -does- force using the pure perl
+Dumper rather than the XS one, but I've never in my life seen Data::Dumper
+show up in a profile so "who cares?".
+
+=head1 BUT BUT BUT ...
+
+Yes, we know. Consider this module in the ::Tiny spirit and feel free to
+write a Data::Dumper::Concise::ButWithExtraTwiddlyBits if it makes you
+happy. Then tell us so we can add it to the see also section.
+
+=head1 SUGARY SYNTAX
+
+This package also provides:
+
+L<Data::Dumper::Concise::Sugar> - provides Dwarn and DwarnS convenience functions
+
+L<Devel::Dwarn> - shorter form for Data::Dumper::Concise::Sugar
+
+=head1 SEE ALSO
+
+We use for some purposes, and dearly love, the following alternatives:
+
+L<Data::Dump> - prettiness oriented but not amazingly configurable
+
+L<Data::Dump::Streamer> - brilliant. beautiful. insane. extensive. excessive. try it.
+
+L<JSON::XS> - no, really. If it's just plain data, JSON is a great option.
+
+=head1 AUTHOR
+
+mst - Matt S. Trout <mst@shadowcat.co.uk>
+
+=head1 CONTRIBUTORS
+
+frew - Arthur Axel "fREW" Schmidt <frioux@gmail.com>
+
+=head1 COPYRIGHT
+
+Copyright (c) 2010 the Data::Dumper::Concise L</AUTHOR> and L</CONTRIBUTORS>
+as listed above.
+
+=head1 LICENSE
+
+This library is free software and may be distributed under the same terms
+as perl itself.
+
+=cut
+
+1;

database/perl/vendor/lib/Data/Dumper/Concise/Sugar.pm

@@ -0,0 +1,219 @@
+package Data::Dumper::Concise::Sugar;
+
+use 5.006;
+
+our $VERSION = '2.023';
+
+use Exporter ();
+use Data::Dumper::Concise ();
+
+BEGIN { @ISA = qw(Exporter) }
+
+@EXPORT = qw(
+   $Dwarn $DwarnN Dwarn DwarnS DwarnL DwarnN DwarnF
+   $Ddie $DdieN Ddie DdieS DdieL DdieN DdieD
+);
+
+sub Dwarn { DwarnL(@_); return wantarray ? @_ : $_[0] }
+
+our $Dwarn = \&Dwarn;
+our $DwarnN = \&DwarnN;
+
+sub DwarnL { warn Data::Dumper::Concise::Dumper @_; @_ }
+
+sub DwarnS ($) { warn Data::Dumper::Concise::Dumper $_[0]; $_[0] }
+
+sub DwarnN ($) {
+   require Devel::ArgNames;
+   my $x = Devel::ArgNames::arg_names();
+   warn(($x?$x:'(anon)') . ' => ' . Data::Dumper::Concise::Dumper $_[0]); $_[0]
+}
+
+sub DwarnF (&@) { my $c = shift; warn &Data::Dumper::Concise::DumperF($c, @_); @_ }
+
+sub Ddie { DdieL(@_); return wantarray ? @_ : $_[0] }
+
+our $Ddie = \&Ddie;
+our $DdieN = \&DdieN;
+
+sub DdieL { die Data::Dumper::Concise::Dumper @_ }
+
+sub DdieS ($) { die Data::Dumper::Concise::Dumper $_[0] }
+
+sub DdieN ($) {
+   require Devel::ArgNames;
+   my $x = Devel::ArgNames::arg_names();
+   die(($x?$x:'(anon)') . ' => ' . Data::Dumper::Concise::Dumper $_[0]);
+}
+
+=head1 NAME
+
+Data::Dumper::Concise::Sugar - return Dwarn @return_value
+
+=head1 SYNOPSIS
+
+  use Data::Dumper::Concise::Sugar;
+
+  return Dwarn some_call(...)
+
+is equivalent to:
+
+  use Data::Dumper::Concise;
+
+  if (wantarray) {
+     my @return = some_call(...);
+     warn Dumper(@return);
+     return @return;
+  } else {
+     my $return = some_call(...);
+     warn Dumper($return);
+     return $return;
+  }
+
+but shorter. If you need to force scalar context on the value,
+
+  use Data::Dumper::Concise::Sugar;
+
+  return DwarnS some_call(...)
+
+is equivalent to:
+
+  use Data::Dumper::Concise;
+
+  my $return = some_call(...);
+  warn Dumper($return);
+  return $return;
+
+If you need to force list context on the value,
+
+  use Data::Dumper::Concise::Sugar;
+
+  return DwarnL some_call(...)
+
+is equivalent to:
+
+  use Data::Dumper::Concise;
+
+  my @return = some_call(...);
+  warn Dumper(@return);
+  return @return;
+
+If you want to label your output, try DwarnN
+
+  use Data::Dumper::Concise::Sugar;
+
+  return DwarnN $foo
+
+is equivalent to:
+
+  use Data::Dumper::Concise;
+
+  my @return = some_call(...);
+  warn '$foo => ' . Dumper(@return);
+  return @return;
+
+If you want to output a reference returned by a method easily, try $Dwarn
+
+ $foo->bar->{baz}->$Dwarn
+
+is equivalent to:
+
+  my $return = $foo->bar->{baz};
+  warn Dumper($return);
+  return $return;
+
+If you want to format the output of your data structures, try DwarnF
+
+ my ($a, $c) = DwarnF { "awesome: $_[0] not awesome: $_[1]" } $awesome, $cheesy;
+
+is equivalent to:
+
+  my @return = ($awesome, $cheesy);
+  warn DumperF { "awesome: $_[0] not awesome: $_[1]" } $awesome, $cheesy;
+  return @return;
+
+If you want to immediately die after outputting the data structure, every
+Dwarn subroutine has a paired Ddie version, so just replace the warn with die.
+For example:
+
+ DdieL 'foo', { bar => 'baz' };
+
+=head1 DESCRIPTION
+
+  use Data::Dumper::Concise::Sugar;
+
+will import Dwarn, $Dwarn, DwarnL, DwarnN, and DwarnS into your namespace. Using
+L<Exporter>, so see its docs for ways to make it do something else.
+
+=head2 Dwarn
+
+  sub Dwarn { return DwarnL(@_) if wantarray; DwarnS($_[0]) }
+
+=head2 $Dwarn
+
+  $Dwarn = \&Dwarn
+
+=head2 $DwarnN
+
+  $DwarnN = \&DwarnN
+
+=head2 DwarnL
+
+  sub Dwarn { warn Data::Dumper::Concise::Dumper @_; @_ }
+
+=head2 DwarnS
+
+  sub DwarnS ($) { warn Data::Dumper::Concise::Dumper $_[0]; $_[0] }
+
+=head2 DwarnN
+
+  sub DwarnN { warn '$argname => ' . Data::Dumper::Concise::Dumper $_[0]; $_[0] }
+
+B<Note>: this requires L<Devel::ArgNames> to be installed.
+
+=head2 DwarnF
+
+  sub DwarnF (&@) { my $c = shift; warn &Data::Dumper::Concise::DumperF($c, @_); @_ }
+
+=head1 TIPS AND TRICKS
+
+=head2 global usage
+
+Instead of always just doing:
+
+  use Data::Dumper::Concise::Sugar;
+
+  Dwarn ...
+
+We tend to do:
+
+  perl -MData::Dumper::Concise::Sugar foo.pl
+
+(and then in the perl code:)
+
+  ::Dwarn ...
+
+That way, if you leave them in and run without the
+C<< use Data::Dumper::Concise::Sugar >> the program will fail to compile and
+you are less likely to check it in by accident.  Furthmore it allows that
+much less friction to add debug messages.
+
+=head2 method chaining
+
+One trick which is useful when doing method chaining is the following:
+
+  my $foo = Bar->new;
+  $foo->bar->baz->Data::Dumper::Concise::Sugar::DwarnS->biff;
+
+which is the same as:
+
+  my $foo = Bar->new;
+  (DwarnS $foo->bar->baz)->biff;
+
+=head1 SEE ALSO
+
+You probably want L<Devel::Dwarn>, it's the shorter name for this module.
+
+=cut
+
+1;