NAME

Data::HTMLDumper::Output - Provides the default output for Data::HTMLDumper

SYNOPSIS

    use Data::HTMLDumper;
    # This module will become your output formatter.

DESCRIPTION

This is not a class you need to use directly, but if you want to control what the output of Data::HTMLDumper looks like it will interest you.

Data::HTMLDumper uses Parse::RecDescent to parse the output of Data::Dumper. At most stages, when its productions match corresponding methods of this class are called. Those methods are listed below. By subclassing this class and overriding methods, you can control the output's appearance. You can achieve the same thing by replacing the class outright. In either case, you must tell Data::HTMLDumper by calling its actions method:

    my $your_action_object = YourSubclass->new();
    Data::HTMLDumper->actions($your_action_object);

By using objects, you can save your own state, though this class does not.

METHODS

The following methods are available to generate output. The are described with lists of their parameters and samples of their output. In all cases (except the constructor), the first argument is the invocant, which is not listed.

new

This method is useful only for subclasses which do not need to save state. It blesses a scalar reference. It only exists so that object oriented access is possible.

output

This is called once each time the top level rule matches. It receives an array reference pointing to the text for each expression that matched. It is here to serve calls to Dumper which have multiple references. Mine just interpolates the array into a string (after locally setting $" to "").

expression

This method is called when the top level rule matches. It receives the invocant plus a hash of consumed text from the input. The keys in the hash are SIGIL (usually, or perhaps always, $), ID_NAME (the name of the var as in VAR3), and item (which is the text produced by the methods below for the rest of the expression).

My version looks like this:

  sub expression {
    my $self = shift;
    my %item = @_;

    return "<table border='1'>$item{item}</table>\n";
  }

I won't show any more whole methods, but this shows how easy it is to generate the output. Simply use the input data to build a string. Return that string.

item_value

This should probably be item_simple_value, but I didn't want to type that everywhere. It receives two things: a simple item (like a string, a number, or undef) and a flag telling the item is a hash value or not (true means it is, undefined means it's not).

item_array

This is called when an entire array is seen. Usually the output is already generated, so my routine simply returns its second argument.

item_hash

This is just like item_array, but for hashes. Again, all I do is return the second argument.

item_object

This is the third and final in the series. It receives the object text. Mine returns the second argument.

array

This is called with an array reference listing the output for the items which are the elements of an array. Mine puts them in a row:

    <tr>@$array</tr>

Remember that it receives an array reference.

array_empty

This is called without arguments when an array of the form [] is seen. Do what you like. I give back this:

    <tr><td>NO_ELEMENTS</td></tr>

hash

This is like array above, but it recieves an array of the output for the key/value pairs in the hash. I just stringify it:

    "@$pairs\n";

(but I reset $" locally to "", so no extra spaces separate the entries)

hash_empty

This is just like array_empty except for hashes like {}. I return:

    <tr><td>NO_PAIRS</td></tr>

pair

This is called with a key and its value item, each time a pair is seen in a hash. My output creates a new row (since this is a whole hash), putting the key in the first column and a table around the value in the second.

object

This is called when a blessed reference is found. It receives the object and the class into which it is blessed.

string

This is called whenever a string value is seen. The string is passed in. For HTML output it is wise to replace any html characters with their appropriate entities, for example:

    $text    =~ s/&/&/g;

After several such substitutions, I return the string.

cpanm Data::HTMLDumper

perl -MCPAN -e shell
install Data::HTMLDumper