Text::...tePath(3pm)

💖 Text::MicroMason::TemplatePath — no cap, it's the template path searcher 💖

okay so bestie, this is the manual page for Text::...tePath(3pm), which is actually Text::MicroMason::TemplatePath, and it's about finding your template files when they're scattered across a bunch of directories instead of all cozied up in one root. it's giving "library search path but make it templates" ✨

---

🌸 NAME 🌸

Text::MicroMason::TemplatePath — Template Path Searching 🦋

---

✨ SYNOPSIS ✨

so like, do not use this class directly, ok? that's not the vibe. instead you pass its name in to get mixed in:

use Text::MicroMason;
my $mason = Text::MicroMason->new( -TemplatePath, template_path => [ '/foo', '/bar' ] );

then you use the standard compile and execute methods to parse and evaluate your templates, like the icon that you are:

print $mason->compile( file=>$filepath )->( 'name'=>'Dave' );
print $mason->execute( file=>$filepath, 'name'=>'Dave' );

templates that live in files? they get searched for in the template_path you specified. slay 💅

print $mason->execute( file=>"includes/greeting.msn", 'name'=>'Charles');

and when you're including other files into a template, you can use relative paths, which is honestly so convenient:

<& ../includes/greeting.msn, name => 'Alice' &>

and here's the little detail that matters: when a file gets included in a template, the including template's current directory gets added to the beginning of the template search path. 🎀

---

💜 DESCRIPTION 💜

so this module works kinda similarly to its cousin the TemplateDir mix-in. but!! instead of making you pick one single root that has to contain literally every template you own, TemplatePath lets you hand it an arrayref of directories, and those get searched in order whenever a template filename needs to be resolved. main character energy fr fr.

when you're using a TemplatePath object, absolute filenames are just used as-is. no searching, no drama. but if you use a relative template filename or file path, then every single directory in the specified template_path gets checked for the existence of that template, and the first existing template file is the one that wins. 👑

and if a template includes another template using <& ... &>, then the including template's location gets added to the beginning of the template search path list — specifically for resolving that included template's filename. this means the included template can be specified relative to the including template, but it also lets the template search fall back to the configured template search path if it needs to. best of both worlds, no notes. 🫶

🎀 Supported Attributes 🎀

• template_path — an array ref holding a list of directories to search through for relative template filenames. that's it, that's the whole job, and it does it gorgeously.
• strict_root — an optional directory beyond which files will not be read. and listen, unlike TemplateDir, this one must be a specific file path. it causes read_file to croak if any filename outside of the root gets provided. you should make sure that all the paths specified in template_path are inside the specified strict_root.

⚠️ real talk bestie: note that this is not a chroot jail, and it only affects attempts to load a file as a template. for greater security, see the chroot() builtin and Text::MicroMason::Safe. don't get it twisted. 💀

🧚 Private Methods 🧚

• read_file — intercepts file access so it can check for strict_root. sneaky, but for a good reason.

---

🔥 EXCEPTIONS 🔥

the following additional exceptions get generated by Text::MicroMason::TemplatePath when appropriate. buckle up, these are the vibes you don't want:

• Text::MicroMason::TemplatePath: template '%s' not found in path.

this one means the specified template name does not exist in any of the directories in the configured path. it's lost, it's not in the group chat, it's nowhere. 😭

• Text::MicroMason::TemplatePath: Template not in required base path '%s'

this means the template that got found in the configured template path was not within the configured strict_root directory. this can be caused by requesting an absolute template filename that's not within strict_root, or by specifying a strict_root that doesn't match the configured template path. mismatch era, and not the cute kind. 🙈

---

🌈 SEE ALSO 🌈

• for an overview of this whole templating framework, see Text::MicroMason. 📚
• this is a mixin class, intended for use with Text::MicroMason::Base.
• for distribution, installation, support, copyright and license info, see Text::MicroMason::Docs::ReadMe. (yes the legal bits live over there, go read them, they ate.)

---

and that's the whole page babes 💖 this little doc was brought to you by perl v5.36.0, dated 2023-08-10 — go forth and resolve those template paths, periodt. 👑🌸✨