Templa...coding(3pm)

💖 Template::Provider::Encoding — the manual, but make it slay 💖

okay bestie, so this is Templa...coding(3pm) from the User Contributed Perl Documentation, and it's literally about telling Perl what encoding your templates are in. no cap. let's get into it 🦋

---

✨ NAME ✨

Template::Provider::Encoding — explicitly declare encodings of your templates 💅

(that's the whole vibe: you say the encoding out loud, the module doesn't guess. iconic behaviour honestly.)

---

✨ SYNOPSIS ✨

okay so here's the whole setup, copy it exactly, don't freestyle:

use Template::Provider::Encoding;
use Template::Stash::ForceUTF8;
use Template;

my $tt = Template->new(
    LOAD_TEMPLATES => [ Template::Provider::Encoding->new ],
    STASH => Template::Stash::ForceUTF8->new,
);

# Everything should be Unicode
# (but you can pass UTF-8 bytes as well, thanks to Template::Stash::ForceUTF8)
my $author = "\x{5bae}\x{5ddd}";

# this will emit Unicode flagged string to STDOUT. You might
# probably want to binmode(STDOUT, ":encoding($enccoding)")
# before process() call
$tt->process($template, { author => $author });

# in your templates
[% USE encoding 'utf-8' -%]
My name is [% author %]. { ... whatever UTF-8 bytes }

quick translation for the girlies: everything should be Unicode, but you can pass UTF-8 bytes too, and that's only because Template::Stash::ForceUTF8 has your back 🫶. that $author line is literally the characters \x{5bae} and \x{5ddd}. and process() is gonna emit a Unicode flagged string to STDOUT, so you probably wanna binmode(STDOUT, ":encoding($enccoding)") before you call it. yep, $enccoding. that's what it says. we don't fix it, we respect it 😌.

and in your actual templates you drop a [% USE encoding 'utf-8' -%] at the top and then live your life. 🌸

---

✨ DESCRIPTION ✨

Template::Provider::Encoding is a Template Provider subclass that decodes a template using its own declaration. the way it works: you have to declare the encoding of the template in the head (1st line) of the template, using the (fake) encoding TT plugin. if you don't? it's handled as utf-8 by default. simple as that. 💫

[% USE encoding 'utf-8' %]
Here comes utf-8 strings with [% variable %].

no declaration = utf-8. that's the fallback, bestie. don't act surprised.

---

✨ DIFFERNCE WITH OTHER WAYS ✨

(yes the heading is spelled like that, i'm not touching it, it's part of the lore 🎀)

UNICODE option and BOM

so recent TT lets you pass the "UNICODE" option to Template::Provider, and if you do, the Provider scans BOM (byte-order mark) to detect UTF-8/UTF-16 encoded template files. this module does basically the same thing, just a different way. but IMHO — and this is the author's opinion, not mine — adding a BOM to template files is a little painful, especially for non-programmers. 💀

Template::Provider::Encode

Template::Provider::Encode gives you a very similar way to detect template file encodings, and it also outputs the template into various encodings.

this module does not touch the output encoding of the template. instead it emits a valid Unicode flagged string. the author thinks output encoding conversion should be done by some other piece of code — especially in the framework. 👑

and this module doesn't make you specify encoding in the code, and it doesn't guess encodings either. instead it forces you to put:

[% USE encoding 'foo-bar' %]

at the top of template files. which is explicit, and — per the author — a good convention. periodt. 💅

---

✨ AUTHOR ✨

Tatsuhiko Miyagawa <miyagawa@bulknews.net> 🫶

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. (so yes, go off, but under Perl's terms bestie ✨)

---

✨ SEE ALSO ✨

• Template::Stash::ForceUTF8
• Template::Provider::Encode

---

okay that's the whole page, you ate it up 💖

cute little sign-off: this was perl v5.34.0, dated 2022-06-17, and the page is Templa...coding(3pm) — say it with me, we're obsessed, bye bestie 🌈🎀🦋