NAME

HTML::Debug - Enables the output of variable and query debugging information for display in HTML.

SYNOPSIS

        use HTML::Debug;
        my $obj = HTML::Debug->new();
        # do some stuff with $obj here...

DESCRIPTION

HTML::Debug allows the developer to add variables and queries to HTML debugging output. The variables and their values will be color-coded based on type. The queries are displayed with their name, SQL statement, database driver, database name, number of records affected, bind values, and the script name the query is from. The variables are displayed in alphabetical order and the queries are displayed in the order they were added to the debugging.

This module makes use of Data::Dumper to do the hard work of displaying the actual variable values. Some string manipulation is done on the output of Data::Dumper, but just for aesthetic reasons.

The + and += operators have been overloaded to emulate the add() method.

The "" operator has also been overloaded so you can: print $obj; and not have to worry about the make() method.

METHODS

The following section documents the methods for HTML::Debug.

$obj->new()

Creates a new HTML::Debug object. This object will hold the debugging information sent to it. The new method takes one optional parameter if this parameter evaluates to true, then the output will automatically be printed when the object goes out of scope (or whenever the DESTROY method is called).

Example:

my $obj = HTML::Debug->new(); or

my $obj = HTML::Debug->new(1);

$obj->add()

This method adds a variable to the debugging. The first parameter is a string indicating the name of the variable. The second parameter is a scalar or reference to the value of the variable. For instance if you have an array, pass in \@array. You may pass in any variable value including scalars, references, blessed references, hashrefs, arrayrefs, typeglobs, and subroutines. Although, since Data::Dumper is used for the output, passing in typeglobs and subroutines is not very useful.

Example:

$obj->add('myvar', $myvar);

$obj->make()

This method generates the HTML that represents the debugging information. It would most commonly be used to print the debugging info. The variables are displayed first in alphabetical order and are color-coded based on type. All hash values are displayed alphabetically. In addition, the variable names are prefaced with the correct sigil corresponding to their ref type.

The queries are displayed last and are in the order that they were added to the HTML::Debug object. Information displayed with each query include: the query's name, the script on which it ran, the number of rows affected, the database driver name, the database name, the SQL statement, and the bind values, if any.

The variable names, variable values, SQL statements, and bind values are HTML-escaped before output.

Example:

print $obj->make();

$obj += []

The + and += operators have been overloaded to support adding variables and queries to the debugging info. The second argument must either be a scalar, in which case you are adding an anonymous value. Otherwise it must be an arrayref. If the arrayref has two or more elements, it is treated as an ordinary variable, with the first element being the name and the second being the value. If the value is a statement handle, it is treated as a query with the remaining elements being the bind values.

Examples:

$obj += ['myvar', $value];

$obj = $obj + ['myvar', $value];

$obj + ['myvar', $value];

$obj += 3; #anonymous variable

$obj->your_varname()

To make it easy to add the same variable multiple times and see all the values appended into an array, the AUTOLOAD method has been implemented so you can use your variable name as a method name. For example:

$obj->i($i);

If inside a loop, you will see a value of $i for each cycle through the loop.

$obj->DESTROY()

To avoid extra typing, the HTML output is printed when the object goes out of scope assuming you initalized the object to do that by specifying HTML::Debug->new(1).

Mason config

Here is how you would configure HTML::Debug to work with HTML::Mason:

In httpd.conf: PerlSetVar MasonAllowGlobals $d

In autohandler: <%once> use HTML::Debug; </%once>

<%init> local $d = HTML::Debug->new(); </%init>

<%cleanup> $m->print( $d->make() ); </%cleanup>

BUGS

Hopefully none.

AUTHOR

Mike Randall <randall@ku.edu>

MAINTAINER

Mike Randall <randall@ku.edu>