Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Data::Dumper::Simple(3User Contributed Perl DocumentatiData::Dumper::Simple(3)

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
       o   Data::Dumper	- Stringified perl data	structures

       o   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
       o   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.

       o   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.

       o   Slices

	   List	and hash slices	are not	supported at this time.

       o   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.

       o   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!

       o   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.

perl v5.24.1			  2017-07-02	       Data::Dumper::Simple(3)

NAME | SYNOPSIS | ABSTRACT | DESCRIPTION | EXPORT | SEE ALSO | BUGS | LIMITATIONS | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Data::Dumper::Simple&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help