.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "HTML::Template::Dumper 3pm"
.TH HTML::Template::Dumper 3pm "2022-06-14" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
.Vb 1
\&  HTML::Template::Dumper \- Output template data in a test\-friendly format
.Ve
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\&  # Switch the module used to the regular HTML::Template when you\*(Aqre 
\&  # finished testing
\&  #
\&  #use HTML::Template;
\&  use HTML::Template::Dumper;
\&  
\&  my $tmpl = 
\&        #HTML::Template
\&        HTML::Template::Dumper
\&        \->new( . . . );
\&  $tmpl\->set_output_format( \*(AqYAML\*(Aq ) if $tmpl\->isa( \*(AqHTML::Template::Dumper\*(Aq );
\&  
\&  # Do processing for the template
\&  
\&  $tmpl\->output();
.Ve
.SH "DESCRIPTION"
.IX Header "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 \f(CW\*(C`Data::Dumper\*(C'\fR (default) or \f(CW\*(C`YAML\*(C'\fR.
.PP
Note that the underlieing HTML::Template methods are still called, so 
options like \f(CW\*(C`strict\*(C'\fR and \f(CW\*(C`die_on_bad_params\*(C'\fR will still throw errors.
.SH "USAGE"
.IX Header "USAGE"
.SS "new"
.IX Subsection "new"
Called just like the \f(CW\*(C`HTML::Template\->new()\*(C'\fR method.
.SS "set_output_format"
.IX Subsection "set_output_format"
.Vb 1
\&  $tmpl\->set_output_format( \*(AqYAML\*(Aq, @extra_params );
.Ve
.PP
Set the output format.  Currently known formats are:
.PP
.Vb 4
\&  Format Name         Module
\&  \-\-\-\-\-\-\-\-\-\-\-\-\-       \-\-\-\-\-\-\-\-
\&  Data_Dumper         HTML::Template::Dumper::Data_Dumper
\&  YAML                HTML::Template::Dumper::YAML
.Ve
.PP
The module is found by applying the following rules:
.IP "1." 4
If the name has a \f(CW\*(C`::\*(C'\fR anywhere, then it is taken as the full name 
of the module.
.IP "2." 4
Otherwise, the module is loaded from \f(CW\*(C`HTML::Template::Dumper::$NAME\*(C'\fR, 
where \f(CW$NAME\fR is what you passed to \f(CW\*(C`set_output_format\*(C'\fR.
.IP "3." 4
If the name didn't have a \f(CW\*(C`::\*(C'\fR in it, but it didn't pass rule #2, then 
take it as the full name of the module.
.IP "4." 4
If none of the above work, then call \f(CW\*(C`die\*(C'\fR.
.PP
In any of the cases, the module returned must inheirt from 
\&\f(CW\*(C`HTML::Template::Dumper::Format\*(C'\fR.  Otherwise, \f(CW\*(C`die\*(C'\fR is called.
.PP
Any parameters you pass after the format will be put directly into the 
formatter's \f(CW\*(C`new()\*(C'\fR method.
.SS "output"
.IX Subsection "output"
Called just like the regular \f(CW\*(C`HTML::Template\->output()\*(C'\fR, but will 
return a simplified view of the template data instead of the full 
object.
.PP
The \f(CW\*(C`print_to\*(C'\fR parameter is respected as specified in the 
\&\f(CW\*(C`HTML::Template\*(C'\fR documentation.
.SS "set_output_filter"
.IX Subsection "set_output_filter"
Called with a reference to a subroutine. Before \f(CW\*(C`output\*(C'\fR returns, this 
subroutine will be called with a scalar reference to the data that would 
otherwise have been directly returned by \f(CW\*(C`output\*(C'\fR. Your filter subroutine 
can do any modification on the value it wants.  For instance, if you want 
the output to be (almost) valid \s-1HTML,\s0 you could write:
.PP
.Vb 10
\&  $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>
\&        }
\&  });
.Ve
.PP
Note that the result may or may not work with \f(CW\*(C`parse\*(C'\fR, depending on your 
filter and the format used by your dumper.
.SS "parse"
.IX Subsection "parse"
Called with the data that was returned by \f(CW\*(C`output()\*(C'\fR.  Returns 
a hashref of all the parameters.
.PP
This can also be called as a class method, in which case it can take a 
second parameter containing the data format that the first parameter is
in.  This second parameter has the same rules applied to it as 
\&\f(CW\*(C`set_output_format()\*(C'\fR.
.SH "WRITING NEW FORMATTERS"
.IX Header "WRITING NEW FORMATTERS"
Formaters must inheirt from \f(CW\*(C`HTML::Template::Dumper::Format\*(C'\fR.
There are two methods that need to be overridden.
.SS "new"
.IX Subsection "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.
.SS "dump"
.IX Subsection "dump"
All formatters must override this method.
.PP
It is called with a single reference which is formatted and returned.
.SS "parse"
.IX Subsection "parse"
All formaters must override this method.
.PP
It is called with a single scalar that holds the complete data returned 
by this formatter's \f(CW\*(C`dump\*(C'\fR method.  It returns a hashref of all the 
parameters held in that dump.
.SH "BUGS"
.IX Header "BUGS"
Yes.
.SH "AUTHOR"
.IX Header "AUTHOR"
.Vb 3
\&  Timm Murray <tmurray@agronomy.org>
\&  http://www.agronomy.org
\&  CPAN ID: TMURRAY
.Ve
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2003, American Society of Agronomy. All rights reserved.
.PP
This program is free software; you can redistribute it and/or modify
it under the terms of either:
.PP
a) the \s-1GNU\s0 General Public License as published by the Free Software 
Foundation; either version 2, or (at your option) any later version, or
.PP
b) the \*(L"Artistic License\*(R" which comes with Perl.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBperl\fR\|(1). \fBHTML::Template\fR\|(3). \fBData::Dumper\fR\|(3). \s-1\fBYAML\s0\fR\|(3).