Provided by: libhtml-template-dumper-perl_0.1-1_all bug

NAME
         HTML::Template::Dumper - Output template data in a test-friendly format


SYNOPSIS
         # Switch the module used to the regular HTML::Template when you're
         # finished testing
         #
         #use HTML::Template;
         use HTML::Template::Dumper;

         my $tmpl =
               #HTML::Template
               HTML::Template::Dumper
               ->new( . . . );
         $tmpl->set_output_format( 'YAML' ) if $tmpl->isa( 'HTML::Template::Dumper' );

         # Do processing for the template

         $tmpl->output();


DESCRIPTION
       This module helps you to test HTML::Template-based programs by printing only the
       information used to fill-in the template data.  This makes it much easier to automatically
       parse the output of your program.  Currently, data can be outputed by "Data::Dumper"
       (default) or "YAML".

       Note that the underlieing HTML::Template methods are still called, so options like
       "strict" and "die_on_bad_params" will still throw errors.


USAGE
   new
       Called just like the "HTML::Template->new()" method.

   set_output_format
         $tmpl->set_output_format( 'YAML', @extra_params );

       Set the output format.  Currently known formats are:

         Format Name         Module
         -------------       --------
         Data_Dumper         HTML::Template::Dumper::Data_Dumper
         YAML                HTML::Template::Dumper::YAML

       The module is found by applying the following rules:

       1.  If the name has a "::" anywhere, then it is taken as the full name of the module.

       2.  Otherwise, the module is loaded from "HTML::Template::Dumper::$NAME", where $NAME is
           what you passed to "set_output_format".

       3.  If the name didn't have a "::" in it, but it didn't pass rule #2, then take it as the
           full name of the module.

       4.  If none of the above work, then call "die".

       In any of the cases, the module returned must inheirt from
       "HTML::Template::Dumper::Format".  Otherwise, "die" is called.

       Any parameters you pass after the format will be put directly into the formatter's "new()"
       method.

   output
       Called just like the regular "HTML::Template->output()", but will return a simplified view
       of the template data instead of the full object.

       The "print_to" parameter is respected as specified in the "HTML::Template" documentation.

   set_output_filter
       Called with a reference to a subroutine. Before "output" returns, this subroutine will be
       called with a scalar reference to the data that would otherwise have been directly
       returned by "output". Your filter subroutine can do any modification on the value it
       wants.  For instance, if you want the output to be (almost) valid HTML, you could write:

         $tmpl->set_output_filter( sub {
               my $ref = shift;
               $$ref = q{
                       <html>
                       <head>
                       <title>Debugging Output</title>
                       </head>
                       <body bgcolor="#FFFFFF">
                       <pre>
               } . $$ref . q{
                       </pre>
                       </body>
                       </html>
               }
         });

       Note that the result may or may not work with "parse", depending on your filter and the
       format used by your dumper.

   parse
       Called with the data that was returned by "output()".  Returns a hashref of all the
       parameters.

       This can also be called as a class method, in which case it can take a second paramter
       containing the data format that the first paramter is in.  This second parameter has the
       same rules applied to it as "set_output_format()".


WRITING NEW FORMATTERS
       Formaters must inheirt from "HTML::Template::Dumper::Format".  There are two methods that
       need to be overridden.

   new
       Not called with anything.  Returns a blessed reference.  The default implementation
       blesses a scalar reference in order to save a little memory.  This should be sufficient
       for most formatters, but you can always override this method if you need it.

   dump
       All formatters must override this method.

       It is called with a single reference which is formatted and returned.

   parse
       All formaters must override this method.

       It is called with a single scalar that holds the complete data returned by this
       formatter's "dump" method.  It returns a hashref of all the parameters held in that dump.


BUGS
       Yes.


AUTHOR
         Timm Murray <tmurray@agronomy.org>
         http://www.agronomy.org
         CPAN ID: TMURRAY


COPYRIGHT
       Copyright 2003, American Society of Agronomy. All rights reserved.

       This program is free software; you can redistribute it and/or modify it under the terms of
       either:

       a) the GNU General Public License as published by the Free Software Foundation; either
       version 2, or (at your option) any later version, or

       b) the "Artistic License" which comes with Perl.


SEE ALSO
       perl(1). HTML::Template(3). Data::Dumper(3). YAML(3).