Constructor method which accept a reference to a hash array containing the structure as shown in this example:

$doc = Template::Document->new({
    BLOCK => sub { # some perl code; return $some_text },
    DEFBLOCKS => {
        header => sub { # more perl code; return $some_text },
        footer => sub { # blah blah blah; return $some_text },
    },
    METADATA => {
        author  => 'Andy Wardley',
        version => 3.14,
    }
}) || die $Template::Document::ERROR;

BLOCK and DEFBLOCKS items may be expressed as references to Perl subroutines or as text strings containing Perl subroutine definitions, as is generated by the Template::Parser module. These are evaluated into subroutine references using eval().

Returns a new Template::Document object or undef on error. The error() class method can be called, or the $ERROR package variable inspected to retrieve the relevant error message.

Main processing routine for the compiled template document. A reference to a Template::Context object should be passed as the first parameter. The method installs any locally defined blocks via a call to the context visit() method, processes its own template, (passing the context reference as a parameter) and then calls leave() in the context to allow cleanup.

print $doc->process($context);

Returns a text string representing the generated output for the template. Errors are thrown via die().

Returns a reference to the main BLOCK subroutine.

Returns a reference to the hash array of named DEFBLOCKS subroutines.

Returns a reference to a hash of variables used in the template. This requires the TRACE_VARS option to be enabled.

An autoload method returns METADATA items.

print $doc->author();

This method generate a Perl representation of the template.

my $perl = Template::Document->as_perl({
    BLOCK     => $main_block,
    DEFBLOCKS => {
        foo   => $foo_block,
        bar   => $bar_block,
    },
    METADATA  => {
        name  => 'my_template',
    }
});

This method is used to write compiled Perl templates to disk. If the COMPILE_EXT option (to indicate a file extension for saving compiled templates) then the Template::Parser module calls this subroutine before calling the new() constructor. At this stage, the parser has a representation of the template as text strings containing Perl code. We can write that to a file, enclosed in a small wrapper which will allow us to subsequently require() the file and have Perl parse and compile it into a Template::Document. Thus we have persistence of compiled templates.

This is a simple handler used to catch any errors that arise when the compiled Perl template is first evaluated (that is, evaluated by Perl to create a template subroutine at compile, rather than the template being processed at runtime).

This is mapped to utf8::is_utf8 for versions of Perl that have it (> 5.008) or to Encode::is_utf8 for Perl 5.008. Earlier versions of Perl are not supported.