Data::...Simple(3pm)

💖 NAME 💖

Data::Dumper::Simple — dump your variables with their names, bestie. no more $VAR1, $VAR2 mystery boxes 💅

---

✨ SYNOPSIS ✨

  use Data::Dumper::Simple;
  warn Dumper($scalar,  @array,  %hash);
  warn Dumper($scalar, \@array, \%hash);
  warn Dumper $scalar, @array, %hash;

---

🎀 ABSTRACT 🎀

okay so this module lets you dump variables in a Data::Dumper format. but here's the tea ☕ — unlike the default behavior of Data::Dumper, your variables actually come out named (instead of $VAR1, $VAR2, etc.).

Data::Dumper does provide an extended interface that lets the programmer name the variables, but that interface requires a lot of typing and is prone to tyops (sic). this module fixes that. periodt. 🫶

---

🦋 DESCRIPTION 🦋

Data::Dumper::Simple is actually a source filter that replaces all instances of Dumper($some, @args) in your code with a call to Data::Dumper->Dump(). you get one function and it makes dumping variables for debugging a genuinely trivial task. slay.

ngl though, note that this is primarily a debugging tool. Data::Dumper offers a bit more than that, so don't expect this module to be more than it is. set your expectations accordingly bestie 😌

also note: if you strongly object to source filters, the author has also released Data::Dumper::Names. it does what this module does but it uses PadWalker instead of a source filter. unfortunately, it has a few limitations and is not as powerful as this module. think of Data::Dumper::Names as a "proof of concept". 🧚

🌸 The Problem 🌸

frequently, we use Data::Dumper to dump out some variables while debugging. when this happens, we often do this:

 use Data::Dumper;
 warn Dumper($foo, $bar, $baz);

and we get simple output like:

 $VAR1 = 3;
 $VAR2 = 2;
 $VAR3 = 1;

while this is usually what we want, this can be confusing if we forget which variable corresponds to which variable printed 😭. to get around this, there is an extended interface to Data::Dumper:

  warn Data::Dumper->Dump(
    [$foo, $bar, $baz],
    [qw/*foo *bar *baz/]
  );

this provides much more useful output.

  $foo = 3;
  $bar = 2;
  $baz = 1;

(there's more control over the output than what's shown here, just fyi.)

you can even use this to output more complex data structures:

  warn Data::Dumper->Dump(
    [$foo, \@array],
    [qw/*foo *array/]
  );

and get something like this:

  $foo = 3;
  @array = (
             8,
             'Ovid'
           );

unfortunately, this can involve a lot of annoying typing. 💀

  warn Data::Dumper->Dump(
    [$foo, \%this, \@array, \%that],
    [qw/*foo *that *array *this/]
  );

you'll also notice a typo in the second array ref which can cause great confusion while debugging. it's giving chaos, honestly.

👑 The Solution 👑

with Data::Dumper::Simple you can do this instead:

  use Data::Dumper::Simple.
  warn Dumper($scalar, @array, %hash);

note that there's no need to even take a reference to the variables. the output of the above resembles this (sample data, of course):

  $scalar = 'Ovid';
  @array = (
             'Data',
             'Dumper',
             'Simple',
             'Rocks!'
           );
  %hash = (
            'it' => 'does',
            'I' => 'hope',
            'at' => 'least'
          );

taking a reference to an array or hash works as expected, but taking a reference to a scalar is effectively a no-op (because it can turn into a confusing reference to a reference) 🙈

 my $foo   = { hash => 'ref' };
 my @foo   = qw/foo bar baz/;
 warn Dumper ($foo, \@foo);

produces:

 $foo = {
   'hash' => 'ref'
 };
 $foo = [
   'foo',
   'bar',
   'baz'
 ];

note that this means similarly named variables can get quite confusing, as in the example above. lowkey cursed, but here we are.

if you already have a &Dumper function, you can specify a different function name with the as key in the import list:

  use Data::Dumper::Simple as => 'display';
  warn display( $scalar, @array, %hash );

also, if you really, really can't stand typing warn or print, you can turn on autowarn:

  use Data::Dumper::Simple as => 'display', autowarn => 1;
  display($scalar, @array, $some->{ data });

or you can send the output (as a list) to a different function:

  use Data::Dumper::Simple as => 'debug', autowarn => 'to_log';

  sub to_log {
      my @data = @_;
      # some logging function
  }

  debug(
    $customer => @order_nums
  ); # yeah, we support the fat comma "=>" and newlines

---

🌈 EXPORT 🌈

the only thing exported is the Dumper() function.

well, actually that's not really true. nothing is exported. however, a source filter is used to automatically rewrite any apparent calls to Dumper() so that it just Does The Right Thing. ✨ main character energy fr fr.

---

⭐ SEE ALSO ⭐

• Data::Dumper — Stringified perl data structures
• Filter::Simple — Simplified source filtering

---

🍓 BUGS 🍓

this module uses a source filter. if you don't like that, don't use this. there are no known bugs but there probably are some, as this is Alpha Code. 🙃

---

💜 LIMITATIONS 💜

• Calling with a sub

do not try to call Dumper() with a subroutine in the argument list:

  Dumper($foo, some_sub()); # Bad!

the filter gets confused by the parentheses. your author was going to fix this but it became apparent that there was no way that Dumper() could figure out how to name the return values from the subroutines, thus ensuring further breakage. so don't do that.

• Multiple enreferencing

getting really crazy by using multiple enreferencing will confuse things (e.g., \\\\\\$foo), don't do that, either. the author might use Text::Balanced at some point to fix this if it's an issue.

• Slices

list and hash slices are not supported at this time.

• String interpolation

Dumper($foo) can potentially interpolate if it's in a string. this is because of a weird edge case with FILTER_ONLY code which caused a failure on some items being dumped. the author has fixed that, but made the module a wee bit less robust. this will hopefully be fixed in the next release of Text::Balanced.

• Line numbers may be wrong

because this module uses a source filter, line numbers reported from syntax or other errors may be thrown off a little.

this is probably a bug in the source filter implementation, which should use #line directives. as a workaround until this is fixed, put a directive (such as #line 10000) a few lines ahead of the suspected bug. if the error is reported as happening in line 10007, you know to look about eight lines below your directive for the bug. be sure to remove the bogus directive once you find the bug! 🫡

• The parentheses are optional, but the syntax isn't bulletproof

if you try, it's not hard to confuse the parser. patches welcome. 💌

note that this is not a drop-in replacement for Data::Dumper. if you need the power of that module, use it.

---

👑 AUTHOR 👑

Curtis "Ovid" Poe, <eop_divo_sitruc@yahoo.com>

reverse the name to email me. (yes, seriously, that's the whole trick 😭)

---

🎀 COPYRIGHT AND LICENSE 🎀

Copyright 2004 by Curtis "Ovid" Poe

this library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

and that's a wrap bestie!! 🦋💖 this lil doc shipped with perl v5.36.0, dated 2022-10-22, and the page itself is Data::...Simple(3pm) — go forth and dump responsibly, no cap 💅✨🌸