| Subject: | Template::Parser::parse returns what? POD disagrees with in-code comments |
Greetings all
I have a system that auto-generates perl code and TT templates amoungst other things, so I tend to also have to generate an awful lot of trivial unit tests for what would normally be very obvious things.
My current issue is a way to unit test for "well-formedness", or "compilability" of template files, without actually running them.
Fortunately, TT appears to be quite structurally mungable, with lots of places to hang all sorts of neat customisations.
Narrowing things down to the Template::Parser class as the best place to be writing a "template compiles ok" test, I so far have.
# Does a template compile cleanly
# Usage: template_ok( 'relative/path.html' );
sub template_ok {
my $relative_path = shift
or die 'template_ok was not passed a file path';
my $full_path = File::Spec->catfile(
$template_root, $relative_path,
);
my $message = "Template '$relative_path' parses correctly";
# Read in the file
local $/ = undef;
unless ( open( TEMPLATE, $full_path ) ) {
print "# The template '$relative_path' was not found in '$template_root'\n";
return ok( undef, $message );
}
my $content = <TEMPLATE>;
close TEMPLATE;
# Try to parser the contents of the file
my $Document = $Parser->parse( $content );
unless ( $Document ) {
my $error = $Parser->error();
$error =~ s/^/#\t/gm;
print $error . "\n";
}
ok( isa( $Document, 'Template::Document' ), $message );
}
It's a first cut, so "tighten the localisation scope" type issues will get fixed later, and it is just testing code. Anyways, tt works well enough for now and tests according to the Template::Parser documentation.
Now, my problem is that $Parser->parse( $content ) doesn't seem to be returning a Template::Document object.
It returns the raw hash that matches the format that gets passed to the Template::Document constructor, but it doesn't actually return a Template::Document.
Now, looking through the code for Template::Parser, I do notice.
#------------------------------------------------------------------------
# parse($text, $data)
#
# Parses the text string, $text and returns a hash array representing
# the compiled template block(s) as Perl code, in the format expected
# by Template::Document.
#------------------------------------------------------------------------
So, obviously the _current_ code is correctly returning only a hash, at least according to it's own comments.
However, in the pod further down, I find
=head2 parse($text)
The parse() method parses the text passed in the first parameter and
returns a reference to a Template::Document object which contains the
compiled representation of the template text. On error, undef is
returned.
Now, in a couple of other bits of pod in other files, the documentation also agrees that Template::Parser should return a Template::Document object, but this is obviously not the case?
SO! What's the deal? Is the POD wrong, or is the code wrong?