NAME

Data::HTMLDumper - Uses Data::Dumper to make HTML tables of structures

SYNOPSIS

  use Data::HTMLDumper;

  # to take control of the output:
  Data::HTMLDumper->actions($your_action_object);
  # See Data::HTMLDumper::Output.pm for what $your_action_object must do,
  # or see CONTROLLING OUTPUT below for a small example.

  ...

  print Dumper(\%hash, \@list);

  # or to supply names like Data::Dumper->Dump:
  print Data::HTMLDumper->Dump([\%hash, \@list], [qw(hash list)]);

ABSTRACT

  Data::HTMLDumper turns Data::Dumper output into HTML tables.
  It's for those who like Data::Dumper for quick peeks at their
  structures, but need to display the output in a web browser.

DESCRIPTION

If you like to use Data::Dumper for quick and dirty pictures of your structures during development, but you are now developing for the web, this module might be for you. It uses Data::Dumper, but formats the results as HTML tables.

The format of the tables changed with the introduction of Parse::RecDescent with version 0.04. The new tables are more consistent.

As of version 0.06 the Dumper function handles any number of references. The object oriented Dump method works like its analog in Data::Dumper. The rest of the functions (except new) are not yet available (but see 'SPECIAL VARIABLES' for how to avoid needing some of them).

SPECIAL VARIABLES

Several special variables are available as of version 0.06. This include Maxdepth (to limit how deep the traversal goes), Varname (to let you replace $VAR2 with $YourPrefix2), and Sortkeys (which sorts hash keys as strings). Currently you must use these through the following special variables:

    $Data::HTMLDumper::Maxdepth;
    $Data::HTMLDumper::Varname;
    $Data::HTMLDumper::Sortkeys;

Note that to even see the Varname prefix, you must implement your own callback object, perhaps by subclassing Data::HTMLDumper::Output.

CONTROLLING OUTPUT

If you need to change the way the tables appear, you can (as of version 0.06) subclass Data::HTMLDumper::Output to implement your changes. You must also tell Data::HTMLDumper to make the change. Here is a sample similar to one used in test number 09:

    use Data::HTMLDumper;

    Data::HTMLDumper->actions(MyOutput->new());

    my $data = [qw(some data)];

    print Data::HTMLDumper->Dump([$data], ['data']);

    package MyOutput;

    use base 'Data::HTMLDumper::Output';

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

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

This adds a heading row to each table listing the name supplied to Dump (it would use VAR1 if you called Dumper).

The key is to create your own package (MyOutput above) making it inherit from Data::HTMLDumper::Output (e.g. via use base). This saves you having to implement all of the Output methods (of which there are about 12).

EXPORT

Dumper

DEPENDENCIES

Data::Dumper Parse::RecDescent Data::HTMLDumper::Output

BUGS and OMISSIONS

Though Data::Dumper is used, not all (or even most) of its features are implemented.

These features will be added as developer time permits:

    Seen
    Values
    Names
    Reset

Some of these may be implemented depending on interest:

    Terse
    Deepcopy
    Freezer

Here is a list of features that will never be available (with explanations of what to do instead):

Indent

this affects the appearance of the text output. To affect the appearance of the HTML tables (or to do something totally different) implement a subclass of Data::HTMLDumper::Output

Purity

builds fully "eval"able code. What we're doing here is making pretty HTML tables. There is no use to replicating Data::Dumper's ability to restore data structures.

Pad

like indent, this affects the appearance of the output.

Useqq

controls how special characters in strings are masked. HTML requires a different approach, see Data::HTMLDumper::Output->string for an example of the kind of work you need to do to have things rendered properly.

Toaster

allows objects to control how they are displayed. Override the callback method Data::HTMLDumper::Output->object to control object display. Redispatch to the object or its class if you like.

Quotekeys

controls whether quotes are always used around hash keys. Data::HTMLDumper strips these during parsing, whether they appear or not. You can control the appearance of hash keys by overriding Data::HTMLDumper::Output->pair.

Bless

allows the caller to replace the builtin bless with their own function. Since we are only concerned with appearance here, you should implement your own Data::HTMLDumper::Output->object.

Useperl

for developers of Data::Dumper to turn off XS use during debugging.

Deparse

tries to turn code references back into Perl source with B::Deparse.

Attempts to access these concepts through direct use of Data::Dumper is not wise. Doing so will alter the output of Data::Dumper (duh). That new form will not agree with my grammar and Bad Things will happen, such as fatal parsing errors.

Starting with version 0.04 Data::HTMLDumper uses Parse::RecDescent instead of its old regex substitution scheme. This means that your structure will produce nothing but an error if my grammar is not good enough. If that happens to you, please send me a sample of the structure so that I can correct the grammar.

Starting with version 0.06 you can call Data::Dumper with multiple arguments, but the test suite for this is not complete. If you encounter problems, please send in samples of what broke.

SEE ALSO

This module depends on Data::Dumper to do the real work. Check its documentation for details about how to call Dumper and Dump.

As of version 0.06 Data::HTMLDumper uses Data::HTMLDumper::Output to produce the tables. By subclassing it, or replacing it, you can take a considerable amount of control over the appearance of the final output. You could even produce XML or something else.

AUTHOR

Phil Crow, <philcrow2000@yahoo.com<gt>

COPYRIGHT AND LICENSE

Copyright 2003-4 by Phil Crow

This library is free software; you can redistribute it and/or modify it under the same terms as Perl 5.8.0 itself.

CREDITS

Thanks to Dennis Sutch for patches and encouragement to make the module substantially more robust.

cpanm Data::HTMLDumper

perl -MCPAN -e shell
install Data::HTMLDumper