HTML::...Dumper(3pm)

💖 HTML::Template::Dumper 💖

okay bestie so this is the manual for HTML::Template::Dumper — yes the module name has three dots in it in the header (HTML::...Dumper(3pm)), it's giving dramatic abbreviation, we move. It's from the User Contributed Perl Documentation, and it is so useful for testing. Let's get into it 🦋

---

✨ NAME ✨

HTML::Template::Dumper — outputs your template data in a format that's friendly for testing. That's it, that's the whole vibe.

---

🎀 SYNOPSIS 🎀

so like, here's the whole flow. When you're done testing, switch the module back to regular HTML::Template, mkay?

# 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();

notice how you can just comment-swap the module name and everything else stays put? icon behavior honestly.

---

🌸 DESCRIPTION 🌸

This module helps you test your HTML::Template-based programs by printing only the info that gets used to fill in the template data. That means automatically parsing your program's output becomes so much easier, no cap.

Right now the data can be output by Data::Dumper (that's the default) or YAML.

⚠️ heads up bestie: the underlieing HTML::Template methods are still called. So options like strict and die_on_bad_params will still throw errors at you. The drama is preserved 💅

---

🫶 USAGE 🫶

🌈 new

Called exactly like the HTML::Template->new() method. Same energy, different dumper.

💅 set_output_format

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

Set the output format. Currently the known formats are:

• Data_Dumper → HTML::Template::Dumper::Data_Dumper
• YAML → HTML::Template::Dumper::YAML

The module gets found by applying these rules, in order:

1. If the name has a :: anywhere in it, then it's taken as the full name of the module. Done, periodt.
2. Otherwise, the module is loaded from HTML::Template::Dumper::$NAME, where $NAME is whatever you passed to set_output_format.
3. If the name didn't have a :: in it, but it didn't pass rule #2, then it's taken as the full name of the module.
4. If none of the above work, then die is called. 😭

In any of those cases, the module returned must inheirt from HTML::Template::Dumper::Format. Otherwise, die gets called. no exceptions bestie.

Any parameters you pass after the format get put directly into the formatter's new() method. 🎁

⭐ output

Called just like the regular HTML::Template->output(), except it returns a simplified view of the template data instead of the full object. Main character energy.

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 gets 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, and in that case it can take a second parameter containing the data format that the first parameter is in. That 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.

(that's the whole bug section. iconic. no notes.)

---

🌈 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:

1. the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version, or
2. the "Artistic License" which comes with Perl.

---

🦋 SEE ALSO 🦋

• perl(1)
• HTML::Template(3)
• Data::Dumper(3)
• YAML(3)

---

and that's the whole page bestie!! 💖 this one shipped as part of perl v5.34.0, dated 2022-06-14 — so it's vintage in the most slay way possible. go forth, dump your template data, and pass your tests on the first try fr fr 🫶✨