NAME

       Data::Dumper::Simple - Easily dump variables with names

SYNOPSIS

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

ABSTRACT

         This module allow the user to dump variables in a Data::Dumper format.
         Unlike the default behavior of Data::Dumper, the variables are named
         (instead of $VAR1, $VAR2, etc.)  Data::Dumper provides an extended
         interface that allows the programmer to name the variables, but this
         interface requires a lot of typing and is prone to tyops (sic).  This
         module fixes that.

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 can use
       the one function provided to make dumping variables for debugging a trivial task.

       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.

       Note that if you strongly object to source filters, I've also released
       Data::Dumper::Names.  It does what this module does by 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 I've shown.)

       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.

       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.

       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.

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.  I 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.  I've 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.

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.