Template::Document(3)

✨ Template::Document ✨

Okay bestie, so this is the Template::Document page from the Perl docs, and honestly? It's giving "compiled template object realness." Periodt. 💅

---

🌸 NAME 🌸

Template::Document — the compiled template document object. Like, it's the whole vibe of a template after it's been turned into Perl code. No cap. 🎀

---

🦋 SYNOPSIS 🦋

use Template::Document;

$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;

print $doc->process($context);

Like, that's the whole mood. You build a doc, you process it, you print it. Iconic. 🔥

---

💖 DESCRIPTION 💖

So this module defines an object class, and every instance is literally a compiled template document, okay? The Template::Parser module creates a Template::Document instance to encapsulate a template as it gets compiled into Perl code. It's giving "behind the scenes main character energy." 🧚

The constructor method, new(), expects a reference to a hash array containing the BLOCK, DEFBLOCKS and METADATA items. Like, those are the three pillars, bestie. 🫶

The BLOCK item should contain a reference to a Perl subroutine or a textual representation of Perl code, as generated by the Template::Parser module. This is then evaluated into a subroutine reference using eval(). Lowkey genius. ✨

The DEFBLOCKS item should reference a hash array containing further named BLOCKs which may be defined in the template. The keys represent BLOCK names and the values should be subroutine references or text strings of Perl code as per the main BLOCK item. Like, it's the BLOCK's besties. 💜

The METADATA item should reference a hash array of metadata items relevant to the document. It's giving "extra info, but make it cute." 🎀

The process() method can then be called on the instantiated Template::Document object, passing a reference to a Template::Context object as the first parameter. This will install any locally defined blocks (DEFBLOCKS) in the BLOCKS cache in the context (via a call to visit()) so that they may be subsequently resolved by the context. The main BLOCK subroutine is then executed, passing the context reference on as a parameter. The text returned from the template subroutine is then returned by the process() method, after calling the context leave() method to permit cleanup and de-registration of named BLOCKS previously installed. Like, it does the whole song and dance, and honestly? It ate. 💅

An AUTOLOAD method provides access to the METADATA items for the document. The Template::Service module installs a reference to the main Template::Document object in the stash as the template variable. This allows metadata items to be accessed from within templates, including PRE_PROCESS templates. Obsessed. 🌟

Like, here's the header example, okay?

<html>
<head>
<title>[% template.title %]
</head>
...

Template::Document objects are usually created by the Template::Parser but can be manually instantiated or sub-classed to provide custom template components. So you can make your own, bestie. Slay. 👑

---

🌈 METHODS 🌈

💫 new(\%config) 💫

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(). Like, it's doing the most, but in a good way. 😭

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. So if it flops, you'll know. 💀

💫 process($context) 💫

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. Like, it's the whole cycle. 🔄

print $doc->process($context);

Returns a text string representing the generated output for the template. Errors are thrown via die(). So, you know, watch out. 🙈

💫 block() 💫

Returns a reference to the main BLOCK subroutine. That's it. That's the whole vibe. 🎯

💫 blocks() 💫

Returns a reference to the hash array of named DEFBLOCKS subroutines. Like, all the blocks in one place. ✨

💫 variables() 💫

Returns a reference to a hash of variables used in the template. This requires the TRACE_VARS option to be enabled. So like, you gotta turn that on, bestie. 🔧

💫 meta() 💫

Return a reference to a hash of any META items defined in the template. Metadata queen. 👑

💫 AUTOLOAD 💫

An autoload method returns METADATA items. Like, it's magic. 🌟

print $doc->author();

---

🦄 CLASS METHODS 🦄

These methods are used internally. So like, you probably won't touch them, but here they are for the record. 💖

🌸 as_perl($content) 🌸

This method generate a Perl representation of the template. Like, it makes the Perl code for the template. 💻

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

🌸 write_perl_file(\%config) 🌸

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. Like, it's saving your work so you don't have to redo it. Slay. 💅

---

🧚 INTERNAL FUNCTIONS 🧚

🎀 catch_warnings() 🎀

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). So like, it's the warning catcher. 🚨

🎀 is_utf8() 🎀

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. So like, if you're on old Perl, sorry bestie. 😬

---

👑 AUTHOR 👑

Andy Wardley <abw@wardley.org> <http://wardley.org/> — like, the actual legend who made this. Respect. 🫡

---

💜 COPYRIGHT 💜

Copyright (C) 1996-2013 Andy Wardley. All Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. So like, it's free, but don't be weird about it. 💖

---

🌟 SEE ALSO 🌟

Template, Template::Parser — like, go check these out too, bestie. They're the whole ecosystem. 🌈

---

Okay so that's the whole page! This was literally the Template::Document manpage from Perl v5.42.0, dated 2024-06-23. Like, compiled and served fresh. You're welcome, bestie. Slay. 💅✨🎀