Hack 71. Inspect Your Data Structures

Peek into a reference and see how far down it goes.

How do you know the structure of a Perl reference? Is the reference to a hash, an array, an object, a scalar, or something else? Many people suggest the use of Data::Dumper. This module has a method that dumps the data structure as a text string. It works very well, but its main purpose is to serialize a data structure into a string you can eval to recreate the reference and its data.

Most of the time I don't want to save state or eval anything. I just want to see a text representation of the reference. I really like the representation of a data structure that using the x command within the Perl debugger provides.

Dumping References Outside the Debugger

Is it possible to produce this from a Perl program without using the debugger? Yes!

use strict; use Dumpvalue; my $d    = Dumpvalue->new( ); my $hash = {      first_name => 'Tim',      last_name  => 'Allwine',      friends    => [ 'Jon','Nat','Joe' ], }; $d->dumpValue(\\$hash);

This produces the output:

-> HASH(0x80a190)     'first_name' => 'Tim'     'friends' => ARRAY(0x800368)        0  'Jon'        1  'Nat'        2  'Joe'     'last_name' => 'Allwine'

This is the same output that the debugger produces. The HASH line says that $hash is a hash reference. The next level of indentation shows the keys of the hash and their corresponding values. first_name for example points to the string Tim but friends points to an array reference. The contents of that array appear, one at a time, indented one step further with their indices within the array and their values.

This technique is handy when you have to maintain code written by other people. Suppose that you're editing a web program with over 2,000 lines of code. Deep in the code, you find a reference named $someref and you want to see its contents. At the top of the file, add the lines:

use Dumpvalue; my $d = Dumpvalue->new( );

Then while $d and $someref are in scope, add the line:

$d->dumpValue(\\$someref);

When you run it, the code will dump $someref.

Printing to a File

One complaint with this technique is where dumpValue( ) prints. It usually prints to STDOUT, by default, but actually it prints to the currently selected output filehandle. That's a hint. Add a couple of lines to change the filehandle:

open my $fh, '>dump.out'; my $old_fh = select($fh); $d->dumpValue(\\$ref); close $fh; select($old_fh);

Now when you run the program, the dump string will end up in a file called dump.out.

Output in CGI or mod_perl Programs

Dumping the output in CGI or mod_perl programs is more complex. Often you don't want to print to a filehandle at all, as it may change the rendering of the output drastically. Instead, use IO::Scalar to create a filehandle to a string and select that filehandle. Then, undirected print or dumpValue( ) calls will go to this new filehandle. Select the old filehandle and carry on with your program, printing $dump_str when you want.

use IO::Scalar; my $dump_str; my $io  = IO::Scalar->new(\\$dump_str); my $oio = select($io); print '<pre>',"\\n";       # goes to $dump_str $d->dumpvalue(\\$someref); # as does this print '</pre>';           # and this too select($oio);             # old filehandle print $dump_str;          # stdout again when you want it to